Magnum One/Magnum One (Mid-American Digital) (Disc Manufacturing).iso/d16/winbatch.arc/WINBATCH.TXT

Text File | 1991-05-22 | 214KB | 7,296 lines

                                  WinBatch
                                                         User's Manual














            For IBM (R) PC/XT (R), PC/AT (R), PS/2 (R) and compatibles













                                                     Wilson WindowWare
                                       2701 California Ave SW  ste 212
                                                     Seattle, WA 98116

                                                 Orders:[phone]
                                              Support:  [phone]
                                                 Fax:   [phone]





                     Copyright 1988-1991 by Morrie Wilson.
                              All rights reserved.



        No part of this manual may be reproduced or transmitted in any
        form or by any means, electronic or mechanical, including
        photocopying and recording, for any purpose without the
        express written permission of Wilson WindowWare.  Information
        in this document is subject to change without notice and does
        not represent a commitment by Wilson WindowWare.


        The software described herein is furnished under a license
        agreement.  It is against the law to copy this software under
        any circumstances except as provided by the license agreement.













        U.S. Government Restricted Rights

        Use, duplication, or disclosure by the Government is subject to
        restrictions as set forth in subdivision (b)(3)(ii) of the Rights
        in Technical Data and Computer Software clause at 252.227-7013.
        Contractor/manufacturer is Wilson WindowWare/2701 California Ave
        SW /ste 212/Seattle, WA 98116



        Trademarks

        IBM, PC/XT, PC/AT, and PS/2 are registered trademarks of
        International Business Machines Corporation.
        Microsoft and MS-DOS are registered trademarks of Microsoft
        Corporation.
        Windows, Word for Windows, and Excel are trademarks of Microsoft
        Corporation.

        Scramble is a trademark of Diana Gruber.

        Command Post, WinBatch, and WinEdit are trademarks of Wilson
        WindowWare.


        ii

                                                                 CONTENTS




                                    CONTENTS


        CONTENTS                                         iii

        INTRODUCTION                                     vii
          System Requirements                            vii
          About This Manual                              vii
          Notational Conventions                        viii
          Acknowledgements                              viii

        GETTING STARTED                                    1

        TUTORIAL                                           2
          WinBatch Basics                                  2
             What is a Batch File?                         2
             Our First WinBatch File                       2
             Functions and Parameters                      3
             Displaying Text                               4
             Getting Input                                 5
             Using Variables                               6
             Making Decisions                              7
             Branching                                     9
          Exploring WinBatch                              11
             Running Programs                             11
             Display and Input                            12
             Manipulating Windows                         13
             Files and Directories                        16
             Handling Errors                              18
             Selection Menus                              19
             Nicer Dialog Boxes                           22
             Running DOS Programs                         24
             Sending Keystrokes to Programs               24
             Our Completed WinBatch File                  25

        WINBATCH LANGUAGE                                 27
          Language Components                             27
             Constants                                    27
             Identifiers                                  28
             Variables                                    28
             Keywords Are Reserved                        28
             Operators                                    28
             Precedence and evaluation order              29
             Comments                                     30
             Statements                                   30
             Substitution                                 30
          Function Parameters                             31
          Error Handling                                  31
          The Functions & Statements                      32
             Inputting Information                        32
             Displaying Information                       32
             File Management                              32
             Directory Management                         33




                                                                      iii

        CONTENTS



             Disk Drive Management                        33
             Window Management                            34
             Program Management                           34
             String Handling                              35
             Arithmetic Functions                         36
             Clipboard Handling                           36
             System Control                               36

        WBL FUNCTION REFERENCE                            39
          Introduction                                    39
          Abs                                             40
          AskLine                                         40
          AskYesNo                                        41
          Average                                         41
          Beep                                            42
          Call                                            42
          CallExt                                         42
          Char2Num                                        43
          ClipAppend                                      43
          ClipGet                                         44
          ClipPut                                         45
          DateTime                                        45
          Debug                                           46
          Delay                                           47
          DirChange                                       47
          DirGet                                          48
          DirHome                                         48
          DirItemize                                      49
          DirMake                                         49
          DirRemove                                       50
          DiskFree                                        50
          Display                                         51
          DOSVersion                                      51
          Drop                                            52
          EndSession                                      52
          Environment                                     53
          ErrorMode                                       53
          Execute                                         54
          Exit                                            54
          Exclusive                                       55
          FileClose                                       55
          FileCopy                                        56
          FileDelete                                      56
          FileExist                                       57
          FileExtension                                   58
          FileItemize                                     58
          FileLocate                                      59
          FileMove                                        60
          FileOpen                                        60
          FilePath                                        61
          FileRead                                        61
          FileRename                                      62
          FileRoot                                        63




        iv

                                                                 CONTENTS



          FileSize                                        63
          FileWrite                                       64
          Goto                                            64
          If_Then                                         64
          IgnoreInput                                     65
          IniRead                                         65
          IniReadPvt                                      66
          IniWrite                                        66
          IniWritePvt                                     67
          IsDefined                                       67
          IsKeyDown                                       68
          IsLicensed                                      68
          IsNumber                                        69
          ItemSelect                                      69
          LastError                                       70
          LogDisk                                         71
          Max                                             71
          Message                                         72
          Min                                             72
          Num2Char                                        73
          ParseData                                       73
          Pause                                           74
          Random                                          74
          Return                                          74
          Run                                             75
          RunHide                                         75
          RunIcon                                         76
          RunZoom                                         77
          SendKey                                         78
          SKDebug                                         79
          StrCat                                          80
          StrCmp                                          80
          StrFill                                         81
          StrFix                                          81
          StriCmp                                         82
          StrIndex                                        83
          StrLen                                          83
          StrLower                                        84
          StrReplace                                      84
          StrScan                                         85
          StrSub                                          86
          StrTrim                                         86
          StrUpper                                        87
          TextBox                                         87
          Version                                         88
          WinActivate                                     88
          WinArrange                                      89
          WinClose                                        89
          WinCloseNot                                     90
          WinConfig                                       91
          WinExist                                        91
          WinGetActive                                    92
          WinHide                                         92
          WinIconize                                      93




                                                                        v

        CONTENTS



          WinItemize                                      93
          WinPlace                                        94
          WinPosition                                     95
          WinShow                                         96
          WinTitle                                        96
          WinVersion                                      97
          WinWaitClose                                    97
          WinZoom                                         98
          Yield                                           99

        APPENDIX A  Predefined Constants                 100

        APPENDIX B  Errors                               101
          Minor Errors                                   101
          Moderate Errors                                101
          Fatal Errors                                   102

        Index                                            107








































        vi

                                                             INTRODUCTION




                                  INTRODUCTION

        WinBatch is a new batch language interpreter which brings the
        power of batch language programming to the Windows environment.
        WinBatch files can do pretty much everything the old DOS batch
        files could do, but WinBatch goes far beyond the capabilities of
        the DOS batch language.

        WinBatch files can:

          *  Run Windows and DOS programs.
          *  Resize and rearrange windows.
          *  Send keystrokes directly to applications.
          *  Display information to the user in various formats.
          *  Prompt the user for input.
          *  Present scrollable file and directory lists.
          *  Copy, move, delete, and rename files.
          *  Read and write files directly.
          *  Perform string and arithmetic operations.
          *  Make branching decisions based upon numerous factors.

        And much, much more.

        Whether you are creating batch files for others, or looking for a
        way to automate your own work and eliminate the drudgery of
        repetitive tasks, you will find WinBatch to be a powerful,
        versatile, and easy-to-use tool.


        System Requirements

    WinBatch  requires an IBM PC or compatible with a minimum of
        640K memory running Microsoft Windows version 3.0 or higher.


        About This Manual

        This manual is divided into four sections:  First is Getting
        Started (pg. 1), where we tell you how to install the program.
        Then we offer an extensive Tutorial, to get both beginning and
        advanced users quickly up to speed with creating WinBatch files
        (pg. 21).  Then we describe the different elements of the
        WinBatch Language (WBL) (pg. 27).  Finally, there is a
        comprehensive WBL Function Reference (pg. 39), which contains





                                                                      vii

        INTRODUCTION



        detailed information on each of the WinBatch functions and
        statements.


        Notational Conventions

        Throughout this manual, we use the following conventions to
        distinguish elements of text:

        ALL-CAPS
          Used for filenames.

        Boldface
          Used for important points, programs, function names, and parts
          of syntax that must appear as shown.

        system
          Used for menu items as they appear to the user.

        Small fixed-width
          Used for batch file sample code.


        Acknowledgements

    WinBatch designed & written by Morrie Wilson.
        User's Manual designed by Richard Merit.
        Written by Richard Merit & Morrie Wilson.

        Our thanks to the many beta-testers for their invaluable comments
        & suggestions.




























        viii

                                                          GETTING STARTED




                                 GETTING STARTED

        WinBatch is quite easy to install.  You will find an appropriate
        diskette in your WinBatch package.  Take the diskette and insert
        it into your floppy drive.  The WinBatch installation program is
        itself a Windows application, so make sure Windows is running.

        From the Program Manager, doubleclick on the File Manager icon to
        run it.  When File Manager starts, click on the A: or B: drive
        icon, depending on which floppy drive you used.  A directory tree
        will appear for the WinBatch diskette.  You should see a root
        directory icon.  Doubleclick on this icon and a list of filenames
        will appear.  Find the filename SETUP.EXE and doubleclick on it.
        Follow whatever instructions Setup gives you.
        Setup will create the necessary files and place them into a
        directory it will prompt you for.

        As the installation program finishes it will display the
        README.TXT file.  You should take the time to read this file as
        it contains any late-breaking information about your copy of
        WinBatch.




































                                                                        1

        TUTORIAL




                                    TUTORIAL




        WinBatch Basics


        What is a Batch File?

        A batch file, whether a DOS batch file or a WinBatch file, is
        simply a list of commands for the computer to process.  Any task
        which will be run more than once, or which requires entering many
        commands or even a single complicated command, is a candidate for
        a batch file.  For example, suppose you regularly enter the
        following commands to start Windows:
        First:

          cd\windows

        then:

          win

        and then:

          cd\

        Here, you are changing to the Windows directory, running Windows,
        and then returning to the root directory.  Instead of having to
        type these three commands every time you run Windows, you can
        create a DOS batch file, called WI.BAT, which contains those
        exact same commands:

          cd\windows
          win
          cd\

        Now, to start Windows, you merely need to type the single command
        WI, which starts the WI.BAT batch file, which runs your three
        commands.

        WinBatch files work the same way.


        Our First WinBatch File

        Our first Winbatch file will simply start up our favorite Windows
        application: Solitaire.  First, start up Notepad, or any other
        editor which is capable of saving text in pure ASCII format (may
        we suggest WinEdit, from Wilson WindowWare).  Next, enter the
        following line:

          Run("sol.exe","")

        Save the file as SOLITARE.WBT.  Now, run SOLITARE.WBT by starting
        or switching to the File Manager, and either moving the cursor to

        2

                                                                 TUTORIAL



        the file name and pressing Enter, or double-clicking on the file
        name with your mouse.  Presto!  It's Solitaire.

        Okay, that wasn't very impressive.  But it did serve to
        illustrate several important WinBatch points.  They are:

        1.  WinBatch files must be edited and saved in ASCII format.

        2.  WinBatch files should be created with a WBT extension.  When
        WinBatch is first installed, it creates an entry in your WIN.INI
        file which causes files with a WBT extension to be associated
        with WinBatch.  As long as WINBATCH.EXE is located in your DOS
        path, you can place WBT files in any directory and run them by
        simply selecting them.

        3.  After you have created a WBT file, you run it by cursoring to
        it and pressing Enter, or double-clicking on it with your mouse
        (you can also add a WBT file to a program group and run it using
        the Program Manager; see your Windows manual for further
        information).  Whatever method you use, we'll use the term Run to
        refer to selecting and running the file.


        Functions and Parameters

        Now, let's look more closely at the line we entered:

          Run("sol.exe", "")

        The first part, Run, is a WinBatch function.  As you might have
        guessed, its purpose is to run a Windows program.  There are over
        a hundred functions and statements in WinBatch, and each has a
        certain syntax which must be used.  The syntax for all WinBatch
        functions may be found in the WBL Function Reference (pg. 39).
        The entry for Run starts off as follows:

        Syntax:
          Run (program-name, parameters)

        Parameters:
          "program-name" =  the name of the desired .EXE, .COM, .PIF,
                            .BAT file, or a data file.
          "parameters" =    optional parameters as required by the
                            application.

        Like all WinBatch functions, Run is followed by a number of
        parameters, enclosed in parentheses.  Parameters are simply
        additional information which are provided when a particular
        function is used; they made either be required or optional.
        Optional parameters are indicated by being enclosed in brackets.
        In this case, Run has two required parameters: the program name,
        and the parameters which get passed to the application.
        There are several types of parameters which you can use.
        Multiple parameters are separated by commas.  In the example

          Run("sol.exe", "")



                                                                        3

        TUTORIAL



        "sol.exe" and "" are both string constants.  String constants can
        be identified by the quote marks which delimit (surround) them
        (you may use either double ("), single forward (') or single back
        (`) quote marks as string delimiters; the examples in this manual
        will use double quotes).

        You may have noticed how we said earlier that the two parameters
        for the Run function are required, and yet the entry for Run in
        the WBL Function Reference describes the second parameter --
        "parameters" -- as being optional.  Which is correct?  Well, from
        a language standpoint, the second parameter is required.  That
        is, if you omit it, you will get a syntax error, and your batch
        file will not run properly.  However, the program that you are
        running may not need any parameters.  Solitaire, for example,
        does not take any parameters.  The way we handle this in our
        batch file is to specify an empty string -- two quote marks with
        nothing in between -- as the second parameter, as we have done in
        our example above.

        To illustrate this further, let's create a WinBatch file called
        EDIT.WBT, containing the following line:

          Run("notepad.exe", "")

        This is just like our previous file, with only the name of the
        program changed.  Save the file, and run it.  You should now be
        in Notepad.  Now edit the EDIT.WBT file as follows:

          Run("notepad.exe", "solitare.wbt")

        Save the file, exit Notepad, and run EDIT.WBT again.  You should
        now be in Notepad, with SOLITARE.WBT loaded.  As we've just
        demonstrated, Notepad is an example of a program which can be run
        with or without a file name parameter passed to it by WinBatch.

        Before you leave Notepad, modify EDIT.WBT as follows:

          ; This is an example of the Run function in WinBatch
          Run("notepad.exe", "solitare.wbt")

        The semicolon at the beginning of the first line signifies a
        comment, and causes that line to be ignored.  You can place
        comment lines, and/or blank lines anywhere in your WinBatch
        files.  In addition, you can place a comment on the same line as
        a function by preceding the comment with a semicolon.  For
        example:

          Run("sol.exe", "")     ;this is a very useful function

        Everything to the right of a semicolon is ignored.  However, if a
        semicolon appears in a string delimited by quotes, it is
        considered part of the string.


        Displaying Text

        Now, let's modify our SOLITARE.WBT file as follows.  You might as
        well use the EDIT.WBT batch file you created earlier to start up
        Notepad:

        4

                                                                 TUTORIAL



          ; solitare.wbt
          Display(5, "Good Luck!", "Remember ... it's only a game.")
          Run("sol.exe", "")

        And run it.  Notice the message box which pops up on the screen
        with words of encouragement.  That's done by the Display function
        in the second line above.  Here's the reference for the Display
        function:

        Syntax:
          Display (seconds, title, text)

        Parameters:
          seconds = integer seconds to display the message (1-15).
          "title" = Title of the window to be displayed.
          "text" =  Text of the window to be displayed.

        Note that the Display function has three parameters.  The first
        parameter -- in our example, 5 -- is the number of seconds which
        the message box will remain on the screen (you can also make the
        box disappear by pressing a key or mouse button).  This is a
        numeric constant, and -- unlike a string constants -- it does not
        need to be enclosed in quotes (although it can be, if you wish,
        as WinBatch will automatically try to convert string variables to
        numeric variables when necessary, and vice versa).  The second
        parameter is the title of the message box, and the third
        parameter is the actual text displayed in the box.  Now, exit
        Solitaire (if you haven't already done so), and edit SOLITARE.WBT
        by placing a semicolon at the beginning of the line with the Run
        function.  This is a handy way to disable, or "comment out,"
        lines in your WinBatch files when you want to modify and test
        only selected segments.  Your SOLITARE.WBT file should look like
        this:

          ; solitare.wbt
          Display(5, "Good Luck!", "Remember ... it's only a game.")
          ;Run("sol.exe", "")

        Now, experiment with modifying the parameters in the Display
        function.  Try adjusting the value of the first parameter.  If
        you look up Display in the WBL reference section, you will notice
        that the acceptable values for this parameter are 1-15.  If you
        try to use a value outside this range, WinBatch will adjust it to
        "make it fit"; that is, it will treat numbers less than 1 as 1,
        and numbers greater than 15 as 15.  Try it.  Also, try giving it
        a non-integer, such as 2.5, and see what happens.  Play around
        with the text in the two string parameters; try making one, or
        both, empty strings ("").


        Getting Input

        Now, let's look at ways of getting input from a user and making
        decisions based on that input.  The most basic form of input is a
        simple Yes/No response, and, indeed, there is a WinBatch function
        called AskYesNo:




                                                                        5

        TUTORIAL



        Syntax:
          AskYesNo (title, question)

        Parameters
          "title" = title of the question box.
          "question" = question to be put to the user.

        Returns:
          (integer) @YES or @NO, depending on the button pressed.

        You should be familiar with the standard syntax format by now; it
        shows us that AskYesNo has two required parameters.  The
        Parameters section tells us that these parameters both take
        strings (indicated by the quote marks), and tells us what each of
        the parameters means.

        You will notice that there is also a new section here, titled
        Returns.  This selection shows you the possible values that may
        be returned by this function.  All functions return values.  In
        the case of Run and Display, we weren't concerned with the values
        that those functions returned.  But with AskYesNo, the returned
        value is very important, because we will need that information to
        decide how to proceed.  We see that AskYesNo returns an integer
        value.  An integer is simply a non-decimal number, such as 0, 1,
        or 2.  The number 1.5 is not an integer.  We see further that the
        integer value returned by AskYesNo is either @YES or @NO.  @YES
        and @NO are predefined constants in WinBatch.  All predefined
        constants begin with an @ symbol, and we will distinguish them
        further by typing them in all caps.  You will find a list of all
        predefined constants in Appendix A (pg. 100).  Even though the
        words "Yes" and "No" are strings, it is important to remember
        that the predefined constants @YES and @NO are not string
        variables (in fact, they are integers).

        Now, let's modify our SOLITARE.WBT file as follows:

          AskYesNo("Really?", "Do you really want to play Solitaire
            now?")
          Run("sol.exe", "")

        and run it.  You should have gotten a nice dialog box which asked
        if you wanted to play Solitaire, but no matter what you answered,
        it started Solitaire anyway.  This isn't good.  We need a way to
        use the Yes/No response to determine further processing.  First,
        we need to explore the concept and use of variables.


        Using Variables

        A variable is simply a placeholder for a value.  The value that
        the variable stands for can be either a text string (string
        variable) or a number (numeric variable).  If you remember
        Algebra 101, you know that if X=3, then X+X=6.  X is simply a
        numeric variable, which stands here for the number 3.  If we
        change the value of X to 4 (X=4), then the expression X+X is now
        equal to 8.  By the same token, we can say that if Y="morning",
        then "good"+Y="good morning".  If we change the value of Y to


        6

                                                                 TUTORIAL



        "afternoon", then the result of our expression is now "good
        afternoon".  Clear so far?

        Now, we know that the AskYesNo function returns a value of either
        @YES or @NO.  What we need to do is create a variable to store
        the value that AskYesNo returns, so that we can use it later on.
        First, we need to give this variable a name.  In WinBatch,
        variable names must begin with a letter, may contain any
        combination of letters or numbers, and may be from 1 to 30
        characters long.  So, let's use a variable called 'response' (we
        will distinguish variable names in this text by typing them in
        all lowercase letters; we will type function and statement names
        starting with a capital letter.  However, in WinBatch, the case
        is irrelevant, so you can use all lowercase, or all uppercase, or
        whatever combination you prefer).  We assign the value returned
        by the AskYesNo function to the variable called 'response' as
        follows:

          response = AskYesNo("Really?", "Do you really want to play
            Solitaire now?")

        Notice the syntax.  The way that WinBatch process this line is to
        first evaluate the result of the AskYesNo function.  The function
        returns a value of either @YES or @NO.  Then, WinBatch assigns
        this returned value to 'response'.  Therefore, 'response' is now
        equal to @YES or @NO.

        Now, all we need is a way to make a decision based upon this
        variable.


        Making Decisions

        WinBatch provides a way to conditionally execute a statement.
        The way this is done is with the If ... Then statement.
        Actually, there are two parts to this construct: If and Then
        (naturally).  The format is:

          If condition Then function

        The use of If ... Then can be illustrated easily by going back to
        our SOLITARE.WBT file, and making these modifications:

          response = AskYesNo("Really?", "Do you really want to play
            Solitaire now?")
          If response == @YES Then Run("sol.exe", "")

        As you can see, we are using If ... Then to test whether the
        response to the question posed in AskYesNo is @YES.  If it is
        @YES, then we start Solitaire.  If it's not @YES, then we don't
        start Solitaire.  The rule is: if the condition following the If
        keyword is true, then the function following the Then keyword is
        performed.  If the condition following the If keyword is false,
        then anything following the Then keyword is ignored
        There is something extremely important that you should note about
        the condition following the If keyword: the double equal signs
        (==).  In WinBatch, a single equal sign (=) is an assignment



                                                                        7

        TUTORIAL



        operator -- it assigns the value on the right of the equal sign
        to the variable on the left of the equal sign.  As in:

          response = AskYesNo("Really?", "Do you really want to play
            Solitaire now?")

        This is saying, in English: "Assign the value returned by the
        AskYesNo function to the variable called 'response'."  But in the
        statement:

          If response == @YES Then Run("sol.exe", "")

        we do not want to assign a new value to response, we merely want
        to test whether it is equal to @YES.  Therefore, we use the
        double equal sign (==), which is the equality operator in
        WinBatch.  The statement above is saying, in English: "If the
        value of the variable called 'response' is equal to @YES, then
        run the program SOL.EXE."  What would happen if we used a single
        equal sign (=) here instead?  Well, since the single equal sign
        (=) is the assignment operator, Winbatch would first assign the
        value @YES to the variable 'response'.  Then, it would perform
        the If function by testing the condition following the keyword
        If.  Since an assignment operation always results in a true
        condition, the condition following the If keyword would always be
        true, and the function following the Then keyword would always be
        performed, regardless of the value of AskYesNo.

        If you've become confused now, just remember that a single equal
        sign (=) is an assignment operator, used to assign a value to a
        variable.  A double equal sign (==) is an equality operator, used
        to test whether the values on both sides of the operator are the
        same.  If you ever have a problem with one of your WinBatch
        files, the first thing you check should be whether you've used
        '=' instead of '=='.  We cannot emphasize this too strongly!
        We've seen what happens when the condition following the Then
        keyword is true.  But what happens when it is false?  Remember we
        said that when the If condition is false, the Then function is
        ignored.  There will be times, however when we want to perform an
        alternate action in this event.  For example, suppose we want to
        display a message if the user decides he or she doesn't want to
        play Solitaire.  We could say:

          response = AskYesNo("Really?", "Do you really want to play
            Solitaire now?")
          If response == @YES Then Run("sol.exe", "")
          If response == @NO Then Display(5, "Game Canceled", "Smart
            move ... I think the boss is standing behind you.")

        In this case there are two If statements being evaluated, with
        one and only one of them possibly being true (unless the user
        selected the Cancel button, which would abort the batch file
        entirely).  However, this is not very efficient from a processing
        point of view.  Furthermore, what would happen if you had several
        functions you wanted to perform if the user answered 'Yes'?  You
        would end up with something unwieldy, like:




        8

                                                                 TUTORIAL



          response = AskYesNo("Really?", "Do you really want to play
            Solitaire now?")
          If response == @YES Then Display(5, "", "On your mark ...")
          If response == @YES Then Display(5, "", "Get set ...")
          If response == @YES Then Display(5, "", "Go!")
          If response == @YES Then Run("sol.exe", "")

        Clearly, there must be a better way of handling this.


        Branching

        Enter the Goto function.  Goto, in combination with If ... Then,
        gives you complete control over the flow of control in your
        WinBatch files.  Goto does exactly what it says -- it causes the
        flow of control to go to another point in the batch file.  You
        must specify where you want the flow of control to be
        transferred, and you must mark this point with a label.  A label
        is simply a destination address.  The form of the Goto function
        is:

          Goto label

        where label is an identifier that you specify.  The same rules
        apply to label names as to variable names (the first character
        must be a letter, the label name may consist of any combination
        of letters and numbers, and the label name may be from 1 to 30
        characters long).  In addition, the label is preceded by a colon
        at the point where it is being used as a destination address.
        Here's an example:

          response = AskYesNo("Really?", "Do you really want to play
            Solitaire now?")
          If response == @NO Then Goto quit
          Display(5, "", "On your mark ...")
          Display(5, "", "Get set ...")
          Display(5, "", "Go!")
          Run("sol.exe", "")
          :quit

        If the If condition is true (that is, the user answered 'No'),
        then the Goto function is performed.  The Goto statement is
        saying, in English "go to the line marked ':quit' and continue
        processing from there."  Notice how the label 'quit' is preceded
        by colon on the last line, but not on the line with the Goto
        function.  This is important.  Although you can have multiple
        lines in your batch file which say 'Goto quit', you can have only
        one line marked ':quit'.  Of course, you can use many different
        labels in a batch file, just as you can use many different
        variables, as long as each has a unique name.  For example:

          response = AskYesNo("Really?", "Do you really want to play
            Solitaire now?")
          If response == @NO Then Goto quit
          Display(5, "", "On your mark ...")
          Display(5, "", "Get set ...")
          Display(5, "", "Go!")


                                                                        9

        TUTORIAL



          Run("sol.exe", "")
          Goto done
          :quit
          Display(5, "Game Canceled", "Smart move ... I think the boss
            is standing behind you.")
          :done

        This is a little more complicated.  It uses two labels, 'quit'
        and 'done'.  If the user answers 'No', then the If condition is
        true, control passes to the line marked ':quit', and a message is
        displayed.  If, on the other hand, the user answers 'Yes', then
        the If condition is false, and the 'Goto quit' line is ignored.
        Instead, the next four lines are processed, and then the 'Goto
        done' line is unconditionally performed.  The purpose of this
        line is to bypass the Display line which follows by transferring
        control to the end of the batch file.  There is another way to
        keep your batch file processing from "falling through" to
        unwanted lines at the end of a program, and that is with the Exit
        function.  Exit causes a batch file to end immediately.  So, for
        example, we could rewrite the above batch file as follows:

          response = AskYesNo("Really?", "Do you really want to play
            Solitaire now?")
          If response == @NO Then Goto quit
          Display(5, "", "On your mark ...")
          Display(5, "", "Get set ...")
          Display(5, "", "Go!")
          Run("sol.exe", "")
          Exit
          :quit
          Display(5, "Game Canceled", "Smart move ... I think the boss
            is standing behind you.")

        Since the Run function is the last thing we want to do if the
        user answers 'Yes', the Exit function simply ends the program at
        that point.  Note that we could put an Exit function at the end
        of the program as well, but it isn't necessary.  An Exit is
        implied at the end of a WinBatch program.


        This concludes the first part of our tutorial.  You now have the
        building blocks you need to create useful WinBatch files.  In the
        second part, which follows, we will look at a some of the
        WinBatch functions which are available for your use.











        10

                                                                 TUTORIAL
        Exploring WinBatch

        What follows is just a sample of the functions and statements
        available in WinBatch.  These should be sufficient to begin
        creating versatile and powerful batch files.  For complete
        information on these and all WinBatch functions and statements,
        refer to the WBL Function Reference (pg. 39).


        Running Programs

        There are three functions which you can use to start an
        application, each of which shares a common syntax:


        Run (program-name, parameters)

        We've already seen the Run function.  This function starts a
        program in a "normal" window.  Windows decides where to place the
        application's  window on the screen.
        Example:

           Run("Notepad.exe", "myfile.txt")

        If the program has an EXE extension, its extension may be
        omitted:

           Run("Notepad", "myfile.txt")

        Also, you can "run" data files if they have an extension in
        WIN.INI which is associated with a program.  So, if TXT files are
        associated with Notepad:

           Run("myfile.txt", "")

        would start Notepad, using the file MYFILE.TXT.

        When you specify a file to run, WinBatch looks first in the
        current directory, and then in the directories on your DOS Path.
        If the file is not found, WinBatch will return an error.  You can
        also specify a full path name for WinBatch to use, as in:

           Run("c:\windows\apps\winedit.exe", "")


        RunZoom (program-name, parameters)

        RunZoom is like Run, but it starts a program as a full-screen
        window.

        Example:

           RunZoom("excel", "bigsheet.xls")


        RunIcon (program-name, parameters)

        RunIcon starts a program as an icon at the bottom of the screen.
        Example:

           RunIcon("clock", "")


                                                                       11

        TUTORIAL

        Display and Input

        Here we have functions which display information to the user and
        prompt the user for information, plus a couple of relevant system
        functions.

        Display (seconds, title, text)

        Displays a message to the user for a specified time.  The message
        will disappear after the time expires, or after any keypress or
        mouse click.
        Example:

           Display(2, "", "Loading Solitaire now")

        Message (title, text)

        This command displays a message box with a title and text you
        specify, until the user presses the OK button.

        Example:

           Message("Sorry", "That file cannot be found")

        Pause (title, text)

        This command is similar to Message, except an exclamation-point
        icon appears in the message box, and the user can press OK or
    Cancel.  If the user presses Cancel, the batch file exits.  Example:

           Pause("Delete Backups", "Last chance to stop!")
           ;if batch file gets this far, the user pressed OK
           FileDelete("*.bak")

        AskYesNo (title, question)

        Displays a dialog box with a given title, which presents the user
        with three buttons: Yes, No, and Cancel.  If the user selects the
        Cancel button, the batch file is terminated.

        Example:

           response = AskYesNo("End Session", "Are you sure you want to
             leave Windows?"

        AskLine (title, prompt, default)

        Displays a dialog box with a given title, which prompts the user
        for a line of input.  Returns the default if the user just
        presses the OK button.
        Example:

           yourfile = AskLine("Edit File", "Filename:", "newfile.txt")
           Run("notepad", yourfile)

        If you specify a default entry (in this case, NEWFILE.TXT), it
        will appear in the response box, and will be replaced with
        whatever the user types.

        Beep

        Beeps once.
        12

                                                                 TUTORIAL

          Beep

        And if one beep isn't enough for you:

          Beep
          Beep
          Beep


        Delay (seconds)

        Pauses batch file execution.
        The Delay function lets you suspend batch file processing for 1
        to 15 seconds.  Again, you can use multiple occurrences for a
        longer delay:

          Delay(15)
          Delay(15)

        Will insert a 30-second pause.


        Manipulating Windows

        There are a large number of functions which allow you to manage
        the windows on your desktop.  Here are some of them:


        WinZoom (partial-windowname)

        Maximizes an application window to full-screen.


        WinIconize (partial-windowname)

        Turns an application window into an icon.


        WinShow (partial-windowname)

        Shows a window in its "normal" state.


        These three functions are used to modify the size of an already-
        running window.  WinZoom is the equivalent of selecting Maximize
        from a window's control (space-bar) menu, WinIconize is the same
        as selecting Minimize, and WinShow has the same effect as
        selecting Restore.

        The window that you are performing any of these functions on does
        not have to be the active window.  If the specified window is in
        the background, and the WinZoom or WinShow function causes the
        size of the window to change, then the window will be brought to
        the foreground.  The WinZoom function has no effect on a window
        which is already maximized, and WinShow has no effect on an
        already-"normal" window.

        Each of these functions takes a partial windowname as a
        parameter.  The "windowname" is the name which appears in the
        title bar at the top of the window.  You can specify the full
        name if you wish, but it may often be advantageous not to have to
                                                                       13

        TUTORIAL



        do so.  For example, if you are editing the file SOLITARE.WBT in
        a Notepad window open, the windowname will be

          Notepad - SOLITARE.WBT

        You probably don't want to have to hard-code this name into your
        batch file:

          WinZoom("Notepad - SOLITARE.WBT")

        Instead, you can specify the partial windowname 'Notepad':

          WinZoom("Notepad")

        If you have more than one Notepad window open, WinBatch will use
        the first one it finds.

        Note that WinBatch matches the partial windowname starting with
        the first character, so that while

          WinZoom("Note")

        would be correct,

          WinZoom("pad")

        would not result in a match.

        Also, be aware that the case of the title (upper or lower) is
        significant, so:

          WinZoom("notepad")

        would be invalid.

        WinActivate (partial-windowname)

        Makes an application window the active window.
        This function makes a currently-open window the active window.
        If the specified window is an icon, it will be restored to normal
        size; otherwise, its size will not be changed.


        WinClose (partial-windowname)

        Closes an application window.


        WinCloseNot (partial-windowname [, partial-windowname]...)

        Closes all application windows except those specified.

        This function lets you close all windows except the one(s) you
        specify.  For example:

          WinCloseNot("Program Man")

        would leave only the Program Manager open, and:

          WinCloseNot("Program Man, Solit")
        14

                                                                 TUTORIAL



        would leave the Program Manager and Solitaire windows open.


        WinWaitClose (partial-windowname)

        Waits until an application window is closed.
        This function causes your WinBatch file to pause until you have
        manually closed a specified window.  This is a very convenient
        way to have a WinBatch file open several windows sequentially,
        without having unnecessary windows open all over your desktop.
        For example:

          RunZoom("invoices.xls", "") ;balance the books
          WinWaitClose("Microsoft Ex")  ;wait till Excel closed
          RunZoom("sol", "")          ;you deserve a break
          WinWaitClose("Solitaire")     ;wait until Sol closed
          Run("winword", "agenda.doc")  ;more paperwork
          WinWaitClose("Microsoft Wor") ;wait until W4W closed
          Run("clock","")             ;lunchtime yet?

        During the time that the batch file is suspended, the WinBatch
        icon will remain at the bottom of your screen.  You can cancel
        the batch file at any time by selecting the icon and then
        selecting "Terminate" from the menu.


        WinExist (partial-windowname)

        Tells if Window exists.

        This function returns @TRUE or @FALSE, depending on whether a
        matching window can be found.  This gives you a very handy method
        of insuring that only one copy of a given window will be open at
        a time.

        If you've been following this tutorial faithfully from the
        beginning, you probably have several copies of Solitaire running
        at the moment.  You can check by pressing Ctrl-Esc now.  You say
        you've got 5 Solitaire windows open?  Okay, close them all.  Now,
        let's modify our SOLITARE.WBT file.  First, trim out the excess
        lines so that it looks like this:

          Run("sol.exe", "")

        Now, let's use the WinExist function to make sure that WinBatch
        only starts Solitaire if it isn't already running:

          If WinExist("Solitaire") == @FALSE Then Run("sol.exe", "")

        And this should work fine.  Run SOLITARE.WBT twice now, and see
        what happens.  The first time you run it, it should start
        Solitaire; the second (and subsequent) time, it should not do
        anything.

        However, it's quite likely that you want the batch file to do
        something if Solitaire is already running -- namely, bring the
        Solitaire window to the foreground.  This can be accomplished



                                                                       15

        TUTORIAL



        easily by using the WinActivate function, along with a couple of
        Goto statements, as follows:

          If WinExist("Solitaire") == @FALSE Then Goto open
          WinActivate("Solitaire")
          Goto loaded
          :open
          Run("sol.exe", "")
          :loaded

        Note that we can change this to have WinExist check for a 'True'
        value instead, by modifying the structure of the batch file, as
        follows:

          If WinExist("Solitaire") == @TRUE Then Goto activate
          Run("sol.exe", "")
          Goto loaded
          :activate
          WinActivate("Solitaire")
          :loaded

        Either format is perfectly correct, and the choice of which to
        use is merely a matter of personal style.  The result is exactly
        the same.


        EndSession ( )

        Ends the current Windows session.
        This does exactly what it says.  It will not ask any questions,
        so you may want to build in a little safety net:

          Sure = AskYesNo("End Session", "Are you sure you want to exit
            Windows?")
          If Sure == @YES Then EndSession()


        Files and Directories


        DirChange (pathname)

        Changes the directory to the pathname specified.
        Use this function when you want to run a program which must be
        started from its own directory.  'Pathname' may optionally
        include a drive letter.

        Example:

           DirChange("c:\windows\winword")
           Run("winword.exe", "")


        DirGet ( )

        Gets the Current Working Directory.

        This function is especially useful when used in conjunction with
        DirChange, to save and then return to the current directory.

        16

                                                                 TUTORIAL



        Example:

          origdir = DirGet()
          DirChange("c:\windows\winword")
          Run("winword.exe", "")
          DirChange(origdir)


        FileExist (filename)

        Determines if a file exists.

        This function will return @TRUE if the specified file exists, and
        @FALSE if it doesn't exist.
        Example:

           If FileExist("win.bak") == @FALSE Then FileCopy("win.ini",
             "win.bak")
           Run("notepad.exe", "win.ini")


        FileCopy (from-list, to-file, warning)

        Copies files.

        If warning is @TRUE, WinEdit will pop up a dialog box warning you
        if you are about to overwrite an existing file, and giving you an
        opportunity to change your mind.  If warning is @FALSE, it won't.
        Example:

           FileCopy("cmdpost.cpm", "*.sav", @TRUE)
           Run("notepad.exe", "cmdpost.cpm")

        The wildcard (*) will cause cmdpost.cpm to be copied as
        cmdpost.sav.


        FileDelete (file-list)

        Deletes files.

        Example:

           If FileExist("win.bak") == @TRUE Then FileDelete("win.bak")


        FileRename (from-list, to-file)

        Renames files to another set of names.


        We can illustrate the use of the WinBatch file functions with a
        typical batch file application.  Our word processor saves a
        backup copy of each document with a BAK extension, but we want a
        larger safety net when editing important files.  We want to keep
        the five most recent versions of the Winbatch manual.  Here is
        our batch file:



                                                                       17

        TUTORIAL



          If FileExist("winbatch.bak") == @TRUE Then Goto backup
          :edit
          Run("winword.exe", "winbatch.doc")
          Exit
          :backup
          FileDelete("winbatch.bk5")
          FileRename("winbatch.bk4", "winbatch.bk5)
          FileRename("winbatch.bk3", "winbatch.bk4)
          FileRename("winbatch.bk2", "winbatch.bk3)
          FileRename("winbatch.bk1", "winbatch.bk2)
          FileRename("winbatch.bak", "winbatch.bk1)
          Goto edit

        If the file WINBATCH.BAK exists, it means that we have made a
        change to WINBATCH.DOC.  So, before we start editing, we delete
        the oldest backup copy, and perform several FileRename functions,
        until eventually WINBATCH.BAK becomes WINBATCH.BK1.  Notice how
        the flow of control moves to the line labeled ':backup', and then
        back to the line labeled ':edit', and how we terminate processing
        with the Exit statement.  If we did not include the Exit
        statement, the batch file would continue in an endless loop.
        However, this batch file still isn't quite right.  What would
        happen if the file WINBATCH.BK5 didn't exist?  In the DOS batch
        language, the command would return an error and processing would
        continue.  But in WinBatch, the error would be fatal, and cause
        the batch file to abort.

        There are two ways that we can handle this.  We could use an If
        FileExist test before every file operation, and test the returned
        value for a @TRUE before proceeding.  But this would be very
        clumsy, even with such a small batch file.


        Handling Errors

        Luckily, there is a WinBatch system function to help us here:
        ErrorMode.  The ErrorMode function determines what happens if an
        error occurs during batch file processing.  Here's the syntax:


        ErrorMode (mode)

        Specifies how to handle errors.

        Parameters:
          "mode" =  @CANCEL, @NOTIFY, or @OFF.

        Returns:
          (integer) previous error setting.

        Use this command to control the effects of runtime errors.  The
        default is @CANCEL, meaning the execution of the batch file will
        be canceled for any error.

        @CANCEL:  All runtime errors will cause execution to be
        canceled.  The user will be notified which error occurred.




        18

                                                                 TUTORIAL



        @NOTIFY:  All runtime errors will be reported to the user, and
        they can choose to continue if it isn't fatal.

        @OFF:  Minor runtime errors will be suppressed. Moderate and
        fatal errors will be reported to the user.  User has the option
        of continuing if the error is not fatal.

        As you can see, the default mode is @CANCEL, and it's a good idea
        to leave it like this.  However, it is quite reasonable to change
        the mode for sections of your batch files where you anticipate
        errors occurring.  This is just what we've done in our modified
        batch file:

          If FileExist("winbatch.bak") == @TRUE Then Goto backup
          :edit
          Run("winword.exe", "winbatch.doc")
          Exit
          :backup
          ErrorMode(@OFF)
          FileDelete("winbatch.bk5")
          FileRename("winbatch.bk4", "winbatch.bk5)
          FileRename("winbatch.bk3", "winbatch.bk4)
          FileRename("winbatch.bk2", "winbatch.bk3)
          FileRename("winbatch.bk1", "winbatch.bk2)
          FileRename("winbatch.bak", "winbatch.bk1)
          ErrorMode(@CANCEL)
          Goto edit

        Notice how we've used ErrorMode(@OFF) to prevent errors from
        aborting the batch file, and then used ErrorMode(@CANCEL) at the
        end of the backup section to change back to the default mode.
        This is good practice.


        Selection Menus

        So far, whenever we have needed to use a file name, we have hard-
        coded it into our batch files.  For example:

          Run("notepad.exe", "agenda.txt")

        Naturally, there should be a way to get this information from the
        user "on the fly", so that we wouldn't have to write hundreds of
        different batch files.  And there is a way.  Two ways, actually.
        Consider, first, a function that we have already seen, the
        AskLine function:

          file = AskLine("", "Enter Filename to edit?", "")
          Run("notepad.exe", file)

        This will prompt the user for a filename, and start Notepad using
        that file.

        There are only three problems with this approach.  First, the
        user might not remember the name of the file.  Second, the user
        might enter the name incorrectly.  And finally, modern software




                                                                       19

        TUTORIAL



        is supposed to be sophisticated enough to handle these things the
        right way.  And WinBatch certainly can.

        There are two new functions we need to use for our file selection
        routine: FileItemize and ItemSelect.


        FileItemize (file-list)

        Returns a space-delimited list of files.

        This function compiles a list of filenames and separates the
        names with spaces.  There are several variations we can use:

          FileItemize("*.doc")

        would give us a list of all files in the current directory with a
        DOC extension,

          FileItemize("*.com *.exe")

        would give us a list of all files in the current directory with a
        COM or EXE extension, and

          FileItemize("*.*")

        would give us a list of all files in the current directory.

        Of course, we need to be able to use this file list, and for that
        we use:


        ItemSelect (title, list, delimiter)

        Displays a listbox filled with items from a list you specify in a
        string.  The items are separated in your string by a delimiter
        character.

        This function actually displays the list box.  Remember that
        FileItemize returns a file list delimited by spaces, which would
        look something like this:

          file1.doc file2.doc file3.doc

        When we use ItemSelect, we need to tell it that the delimiter is
        a space.  We do this as follows:

           textfiles = FileItemize("*.doc *.txt")
           yourfile = ItemSelect("Select a file to edit", textfiles, "")
           run("notepad.exe", yourfile)

        First, we use FileItemize to build a list of filenames with DOC
        and TXT extensions.  We assign this list to the variable
        'textfiles'.  Then, we use the ItemSelect function to build a
        list box, passing it the variable 'textfiles' as its second
        parameter.  The third parameter we use for ItemSelect is simply a
        space with quote marks around it; this tells ItemSelect that the
        variable 'textfiles' is delimited by spaces.  Note that this is
        different from the empty string that we've spoken about earlier -

        20

                                                                 TUTORIAL



        - you must include a space between the quote marks.  Finally, we
        assign the value returned by the ItemSelect function to the
        variable 'yourfile', and run Notepad using that file.

        How does ItemSelect get a file name?  As we said, it pops up a
        list box with all the files returned by the FileSelect function.
        Then, you highlight a file, using either the cursor keys or a
        mouse, and select it by pressing Enter, double-clicking on the
        file, or clicking on the OK button.  If you run the above
        example, you'll see it more easily than we can explain it in
        words.

        If the user presses Enter or clicks on the OK button without a
        file being highlighted, ItemSelect returns an empty string.  If
        you want, you can test for this condition:

           textfiles = FileItemize("*.doc *.txt")
           :retry
           yourfile = ItemSelect("Select a file to edit", textfiles, "")
           if yourfile == "" Then Goto retry
           run("notepad.exe", yourfile)


        DirItemize (dir-list)

        Returns a space-delimited list of directories.

        This function works like FileItemize, but instead of returning a
        list of files, it returns a list of directories.  Remember that
        we said FileItemize only lists files in the current directory.
        Often, we want to be able to use files in other directories as
        well.  We can do this by first selecting the appropriate
        directory, using DirItemize and ItemSelect:

          DirChange("\")
          subdirs = DirItemize("*")
          targdir = ItemSelect("Select dir", subdirs, " ")
          DirChange(targdir)
          files = FileItemize("*.*")
          file = ItemSelect("Select file", files, " ")
          Run("notepad.exe", file)

        First we change to the root directory.  Then we use the
        DirItemize function to get a list of all the subdirectories off
        of root.  Next, we use ItemSelect to give us a list box of
        directories to select from.  Finally, we change to the selected
        directory, and use FileItemize and ItemSelect to pick a file.
        This batch file works, but needs to be polished up a bit.  What
        happens if the file we want is in the \WIN\BATCH directory?  Our
        batch file doesn't go more than one level deep from root.  We
        want  to continue down the directory tree, but we also need a way
        of telling when we're at the end of a branch.  As it happens,
        there is such a way: DirItemize will return an empty string if
        there are no directories to process.  Given this knowledge, we
        can set up a loop to test when we are at the lowest level:



                                                                       21

        TUTORIAL



          DirChange("\")
          :getdir
          subdirs = DirItemize("*")
          If subdirs == "" Then Goto getfile
          targdir = ItemSelect("Select dir (OK for current)", subdirs, "")
          If targdir == "" Then Goto getfile
          DirChange(targdir)
          Goto getdir
          :getfile
          files = FileItemize("*.*")
          file = ItemSelect("Select file", files, " ")
          if file == "" then goto getfile
          Run("notepad.exe", file)

        After we use the DirItemize function, we test the returned value
        for a blank string.  If we have a blank string, then we know that
        the current directory has no subdirectories, and so we proceed to
        select the filename from the current directory (Goto getfile) .
        If, however, DirItemize returns a non-blank list, then we know
        that there is, in fact, at least one directory.  In that case, we
        use ItemSelect to bring up a list box.  Then, we test the value
        returned by ItemSelect.  If the returned value is a blank string,
        it means that the user did not select a directory from the list,
        and presumably wants a file in the current directory.  We happily
        oblige (Goto getfile).  On the other hand, a non-blank value
        returned from ItemSelect indicates that the user has selected a
        subdirectory from the list box.  In that case, we change to the
        selected directory, and loop back to the beginning of the
        directory selection routine (Goto getdir).  We continue this
        until either (a) the user selects a directory, or (b) there are
        no directories left to select.  Eventually, we get down to the
        file selection section of the batch file.


        Nicer Dialog Boxes

        Have you tried displaying long messages, and found that WinBatch
        didn't wrap the lines quite the way you wanted?  Here are a
        couple of tricks.


        Num2Char (integer)

        Converts a number to its character equivalent.

        We want to be able to insert carriage return/line feed
        combinations in our output, and the Num2Char function will let us
        do that.  A carriage return has an ASCII value of 13, and a line
        feed has an ASCII value of 10 (don't worry if you don't
        understand what that means).  To be able to use these values, we
        must convert them to characters, as follows:

          cr = num2char(13)
          lf = num2char(10)






        22

                                                                 TUTORIAL



        Now, we need to be able to place the variables 'cr' and 'lf' in
        our message.  For example, let's say we want to do this:

          Message("", "This is line one This is line two")

        If we just inserted the variables into the string, as in:

          Message("", "This is line one cr lf This is line two")

        we would not get the desired effect (try it and see).  WinBatch
        would  treat them as ordinary text.  However, WinBatch does
        provide us with a method of performing variable substitution such
        as this, and that is by enclosing the variables in percentage
        signs (%%).  If we do this:

          Message("", "This is line one %cr% %lf%This is line two")

        we get what we want.  Note that there is no space after '%lf%';
        this is so the second line will be aligned with the first line
        (every space inside the quote marks is significant).
        Now, wouldn't it be convenient if we could combine cr and lf into
        a single variable?  We can.


        StrCat (string[, string]...)

        Concatenates strings together.

        The StrCat function lets us combine any number of string
        constants and/or string variables.  Here's how we combine the
        variables 'cr' and 'lf' into the single variable 'crlf':

          crlf = StrCat(cr, lf)

        Note that the strings to be concatenated are separated by commas,
        within the parentheses.  Now, we can rewrite our example, as
        follows:

          cr = num2char(13)
          lf = num2char(10)
          crlf = StrCat(cr, lf)
          Message("", "This is line one %crlf%This is line two")

        If we wanted to re-use this message a number of times, it would
        be quite convenient to use the StrCat function to make a single
        variable out of it:

          cr = num2char(13)
          lf = num2char(10)
          crlf = StrCat(cr, lf)
          line1 = "This is line one"
          line2 = "This is line two"
          mytext = StrCat(line1, crlf, line2)
          Message("", mytext)





                                                                       23

        TUTORIAL


        Running DOS Programs

        WinBatch can run DOS programs, just like it runs Windows
        programs:

          dirchange("c:\game")
          run("scramble.exe", "")

        If you want to use an internal DOS command, such as DIR or TYPE,
        you can do so by running the DOS command interpreter,
        COMMAND.COM, with the '/c' program parameter, as follows:

          run("command.com", "/c type readme.txt")

        Everything that you would normally type on the DOS command line
        goes after the '/c' in the second parameter.  Here's another
        example:

          run("command.com", "/c type readme.txt | more")

        These examples assume that COMMAND.COM is in a directory on your
        DOS path.  If it isn't, you could specify a full path name for
        it:

          run("c:\command.com", "/c type readme.txt | more")

        Or, better still, you could use the WinBatch Environment
        function.


        Environment (env-variable)

        Gets a DOS environment variable.
        Since DOS always stores the full path and filename of the command
        processor in the environmental variable COMSPEC, it is an easy
        matter to retrieve this information:

          coms = environment("comspec")

        and use it in our batch file:

          coms = environment("comspec")
          run(coms, "/c type readme.txt")

        To get a DOS window, just run COMMAND.COM with no parameters:

          coms = environment("comspec")
          run(coms, "")


        Sending Keystrokes to Programs

        Here we come to one of the most useful and powerful features of
        WinBatch: the ability to send keystrokes to Windows programs,
        just as if you were typing them directly from the keyboard.

        SendKey (character-codes)

        Sends Keystrokes to the active application.

        24

                                                                 TUTORIAL



        This is an ideal way to automatically program the keys that you
        enter every time you start a certain program.  For example, to
        start up Notepad and have it prompt you for a file to open, you
        would use:

          Run("notepad.exe", "")
          SendKey("!FO")

        The parameter for SendKey is a string to send to the program.
        This string consists of standard characters, as well as some
        special characters which you will find listed under the entry for
        SendKey in the WBL Function Reference (pg. 78).  In the example
        above, the exclamation mark stands for the Alt key, so '!F' is
        the equivalent of pressing and holding down the Alt key while
        simultaneously pressing the 'F' key.  The 'O' in the example
        above is simply the letter 'O', and is the same as pressing the
        'O' key.  As you may know, 'Alt-F' brings up the 'File' menu in
        Notepad, and 'O' selects 'Open' from the 'File' menu.
        Here's another example:

          RunZoom("sol.exe", "")
          SendKey("!GC{RIGHT}{SP}~")

        This starts up Solitaire, brings up the 'Game' menu (!G), selects
        'Deck' (C), moves the cursor to the next card back style on the
        right ({RIGHT}), selects that card back ({SP}), and then selects
        'OK' (~).  And voila!  A different card design every time you
        play!


        Our Completed WinBatch File

        Here is the final version of the SOLITARE.WBT file that we've
        been building throughout this tutorial:

























                                                                       25

        TUTORIAL



          ; solitare.wbt
          mins = AskLine("Solitaire", "How many minutes do you want to
            play?", "")
          If WinExist("Solitaire") == @TRUE Then Goto activate
          RunZoom("sol.exe", "")
          Goto loaded
          :activate
          WinActivate("Solitaire")
          WinZoom("Solitaire")
          :loaded
          SendKey("!GC{RIGHT}{SP}~")
          goal = mins * 60
          timer = 0
          :moretime
          remain = goal - timer
          WinTitle("Solitaire", "Solitaire (%remain% seconds left)")
          delay(10)
          timer = timer + 10
          If WinExist("Solitaire") == @FALSE Then Exit
          If timer < goal Then Goto moretime
          Beep
          WinClose("Solitaire")
          Message("Time's up", "Get back to work!")

        It  incorporates many of the concepts that we've discussed in
        this tutorial, as well as using some arithmetic (*, -, +) and
        relational (<) operators that are covered in the following
        section on the WinBatch language.

        If you can understand and follow the structures and processes
        illustrated in this sample file, and can incorporate them into
        your own WinBatch files, you are well on your way to becoming a
        WinBatch guru!

























        26

                                                        WINBATCH LANGUAGE




                                WINBATCH LANGUAGE




        Language Components

        The statements you write to execute the batch files are
        constructed from constants, variables, operators, functions,
        commands, and comments.

        Constants

        The programming language supports both integer and string
        constants.

        Integer Constants

        Integer constants are built from the digits 0 through 9.  They
        can range in magnitude from negative to positive 231 -1
        (approximately two billion).  Constants larger than these
        permissible magnitudes will produce unpredictable results.

        Examples of integer constants:

                   1
                 -45
              377849
         -1999999999

        String Constants

        String constants are comprised of displayable characters bounded
        by quote marks.  You can use double quotes ("), single quotes
        ('), or back quotes (`) to enclose a string constant, as long as
        the same type of quote is used to both start and end it.  If you
        need to embed the delimiting quote mark inside the string
        constant, use the delimiting quote mark twice.
        Examples of string constants:

          "a"
          `Betty Boop`
          "This constant has an embedded "" mark"
          'This constant also has an embedded " mark'

        Predefined Constants

        The programming language has a number of built-in integer
        constants that can be used for various purposes.  These start
        with the @-sign, and are case-insensitive (although we prefer to
        use ALL CAPS).

        Some predefined constants:

          @FALSE                            @TILE
          @NO                               @TRUE
          @STACK                            @YES

                                                                       27

        WINBATCH LANGUAGE



        A list of all the predefined constants can be found in Appendix
        A: Predefined Constants.

        Identifiers

        Identifiers are the names supplied for variables, functions, and
        commands in your program.
        An identifier is a sequence of one or more letters or digits that
        begins with a letter.  Identifiers may have up to 30 characters.

        All identifiers are case insensitive.  Upper- and lowercase char-
        acters may be mixed at will inside variable names, commands or
        functions.

        For example these statements all mean the same thing:

          AskLine(MyTitle, Prompt, Default)
          ASKLINE(MYTITLE, PROMPT, DEFAULT)
          aSkLiNe(MyTiTlE, pRoMpT, dEfAuLt)

        Variables

        A variable may contain an integer, a string, or a string
        representing an integer.  Automatic conversions between integers
        and strings are performed as a matter of course during execution.

        If a function requires a string parameter and an integer
        parameter is supplied, the variable will be automatically
        modified to include the representative string.
        If a function requires an integer parameter and a string
        parameter is supplied, an attempt will be made to convert the
        string to an integer.  If it does not convert successfully, an
        error will result.

        Keywords Are Reserved

        "Keywords" are the predefined identifiers that have special
        meaning to the programming language.  These cannot be used as
        variable names.

        WBL keywords consist of the functions, commands, and predefined
        constants.

        Some examples of reserved keywords:

          beep
          dirchange
          @Yes
          filecopy

        Operators

        The programming language operators take one operand ("unary
        operators") or two operands ("binary operators").

        Unary operators (integers only):

          -    Arithmetic Negation (Two's complement)

        28

                                                        WINBATCH LANGUAGE



          +    Identity (Unary plus)
          ~    Bitwise Not.  Changes each 0 bit to 1, and vice-versa.
          !    Logical Not.  Produces 0 (@FALSE) if the operand is
               nonzero, else 1 (@TRUE) if the operand is zero.

        Binary arithmetic operators (integers only):

          *    Multiplication
          /    Division
          mod  Modulo
          +    Addition
          -    Subtraction
          <<   Left Shift
          >>   Right Shift
          &    Bitwise And
          |    Bitwise Or
          ^    Bitwise Exclusive Or  (XOR)
          &&   Logical And
          | |     Logical Or

        Binary relational operators (integers and strings):

          >    Greater-than
          >=   Greater-than or equal
          <    Less-than
          <=   Less-than or equal
          ==   Equality
          != or <>Inequality

        Assignment operator (integers and strings):

          =    Assigns evaluated result of an expression to a variable

        Precedence and evaluation order

        The precedence of the operators affect the evaluation of operands
        in expressions.  Operands associated with higher-precedence
        operators are evaluated before the lower-precedence operators.

        The table below shows the precedence of the operators.  Where
        operators have the same precedence, they are evaluated from left
        to right.

        Operator            Description

          ( )               Parenthetical grouping
          ~ ! - +           Unary operators
          * / mod           Multiplication & Division
          + -               Addition & Subtraction
          <<  >>            Shift operators
          < <= == >= > != <>     Relational operators
          & ^ |             Bit manipulation operators
          && | |            Logical operators






                                                                       29

        WINBATCH LANGUAGE


        Comments

        A comment is a sequence of characters that are ignored when
        processing a command.  A semicolon (not otherwise part of a
        string constant) indicates the beginning of a comment.

        All characters to the right of the semicolon are considered
        comments and are ignored.

        Blank lines are also ignored.

        Examples of comments:

          ; This is a comment
          abc = 5 ;This is also a comment

        Statements

        Assignment Statements

        Assignment statements are used to set variables to specific or
        computed values.  Variables may be set to integers or strings.
        Examples:

          a = 5
          value = Average(a, 10, 15)
          location = "Northern Hemisphere"
          World = strcat(location, " ", "Southern Hemisphere")

        Control Statements

        Control statements are generally used to execute system
        management functions and consist of a call to a command without
        assigning any return values.

        Examples:

          run("clock.exe", "")
          delay(5)
          winclose("Clock")
          Exit

        Substitution

        The batch language has a powerful substitution feature which
        inserts the contents of a string variable into a statement before
        the line is parsed.
        To substitute the contents of a variable in the statement, simply
        put a percent-sign (%) on both sides of the variable name.

        Examples:

          MyCmd = "DirChange('C:\')"    ;set MyCmd to a command
          %MyCmd%                ;execute the command

        ...or consider this one:

          IniWrite("PC", "Owner", "Jenny")
          ...
          Owner = IniRead("PC", "Owner", "somebody")
          message("", "This is %Owner%'s PC")
        30

                                                        WINBATCH LANGUAGE




        will produce the output:

          This is Jenny's PC

        To put a single percent-sign (%) on a source line, specify a
        double percent sign(%%).  This is required even inside quoted
        strings.

        Function Parameters

        Most of the functions and commands in the language require
        parameters.  These come in three types:

          Integer
          String
          Variable name

        WinBatch performs automatic conversions between strings and
        integers, so in general you can use them interchangeably.

        Integer parameters may be any of the following:

          An integer (i.e. 23)
          A string representing an integer (i.e. "23")
          A variable containing an integer
          A variable containing a string representing an integer

        String parameters may be any of the following:

          A string
          An integer
          A variable containing a string
          A variable containing an integer

        Error Handling

        There are three types of errors that can occur while processing a
        batch file:  Minor, Moderate, and Fatal.  What happens when an
        error occurs depends on the current error mode, which is set with
        the ErrorMode function.
        There are three possible modes you can specify:

        @CANCEL
          User is notified when any error occurs, and then the batch
          file is canceled.  This is the default.

        @NOTIFY
          User is notified when any error occurs, and has option to
          continue unless the error is fatal.

        @OFF
          User is only notified if the error is moderate or fatal.  User
          has option to continue unless the error is fatal.





                                                                       31

        WINBATCH LANGUAGE


        The function LastError returns the code of the most-recent error
        encountered during the current batch file.

        Minor errors are numbered from 1000 to 1999.
        Moderate errors are numbered from 2000 to 2999.
        Fatal errors are numbered from 3000 to 3999.

        Error handling is reset to @CANCEL at the start of each batch
        file.


        The Functions & Statements


        Inputting Information

        AskLine (title, prompt, default)
          Lets user enter a line of information.

        AskYesNo (title, question)
          Lets user choose from Yes, No, or Cancel.

        ItemSelect (title, list, delimiter)
          Chooses an item from a listbox.

        TextBox (title, filename)
          Fills a listbox from text strings in a file.


        Displaying Information

        Beep
          Beeps at the user.

        Display (seconds, title, text)
          Momentarily displays a string.

        Message (title, text)
          Displays text in a message box.

        Pause (title, text)
          Displays text in a message box.


        File Management

        FileClose (filehandle)
          Closes a file.

        FileCopy (from-list, to-file, warning)
          Copies files.

        FileDelete (file-list)
          Deletes files.

        FileExist (filename)
          Determines if a file exists.

        32

                                                        WINBATCH LANGUAGE

        FileExtension (filename)
          Returns extension of file.

        FileItemize (file-list)
          Builds a list of files.

        FileLocate (filename)
          Finds a file within the current DOS path.

        FileMove (from-list, to-file, warning)
          Moves files to another set of pathnames.

        FileOpen (filename, open-type)
          Opens a STANDARD ASCII (only) file for reading or writing.

        FilePath (filename)
          Returns path of file.

        FileRead (filehandle)
          Reads data from a file.

        FileRename (from-list, to-file)
          Renames files to another set of names.

        FileRoot (filename)
          Returns root of file.

        FileSize (file-list)
          Adds up the total size of a set of files.

        FileWrite (filehandle,output-data)
          Writes data to a file.


        Directory Management

        DirChange ([d:]path)
          Changes the current directory.

        DirGet ( )
          Returns the current directory path.

        DirHome ( )
          Returns the initial directory path.

        DirItemize (dir-list)
          Builds a list of directories.

        DirMake ([d:]path)
          Creates a new directory.

        DirRemove ([d:]path)
          Removes an existing directory.


        Disk Drive Management

        DiskFree (drive-list)
          Returns the amount of free space on a set of drives.

        LogDisk (drive)
          Changes the logged disk drive.
                                                                       33

        WINBATCH LANGUAGE

        Window Management

        WinActivate (partial-windowname)
          Makes an application window the active window.

        WinArrange (style)
          Arranges all running application windows on the screen.

        WinClose (partial-windowname)
          Closes an application window.

        WinCloseNot (partial-windowname [, partial-windowname]...)
          Closes all application windows except those specified.

        WinConfig ( )
          Returns WIN3 mode flags.

        WinExist (partialwindowname)
          Tells if Window exists.

        WinGetActive ( )
          Gets the title of the active window.

        WinHide (partial-windowname)
          Hides an application window.

        WinIconize (partial-windowname)
          Turns an application window into an icon.

        WinItemize ( )
          Lists all the main windows currently running.

        WinPlace (x-ul, y-ul, x-br, y-br, partial-windowname)
          Changes the size and position of an application window on the
          screen.

        WinPosition (partialwindowname)
          Returns Window position.

        WinShow (partial-windowname)
          Shows a currently-hidden application window.

        WinTitle (partial-windowname, new-windowname)
          Changes the title of an application window.

        WinWaitClose (partial-windowname)
          Waits until an application window is closed.

        WinZoom (partial-windowname)
          Maximizes an application window to full-screen.

        Program Management

        Run (program-name, parameters)
          Runs a program as a normal window.

        RunHide (program-name, parameters)
          Runs a program in a hidden window.

        RunIcon (program-name, parameters)
          Runs a program as an icon.
        34

                                                        WINBATCH LANGUAGE



        RunZoom (program-name, parameters)
          Runs a program in a maximized window.


        String Handling

        Char2Num (string)
          Returns the ANSI code of a string's first character.

        IsNumber (string)
          Determines if a string represents a valid number.

        Num2Char (number)
          Converts a number to the ANSI character it represents.

        ParseData (string)
          Parses the passed string, just like passed parameters are
          parsed.

        StrCat (string[, string]...)
          Concatenates strings together.

        StrCmp (string1, string2)
          Compares two strings.

        StrFill (string, string-length)
          Builds a string from a repeated smaller string.

        StrFix (base-string, padding-string, length)
          Pads or truncates a string to a fixed length.

        StrICmp (string1, string2)
          Compares two strings, ignoring their case.

        StrIndex (main-str, sub-str, start, direction)
          Locates a string within a larger string.

        StrLen (string)
          Returns the length of a string
        StrLower (string)
          Converts a string to all lower-case characters.

        StrReplace (string,old,new)
          Replaces all occurrences of a substring with another.

        StrScan (main-str, delims, start, direction)
          Finds an occurrence of one or more delimiter characters in a
          string.

        StrSub (string, start, length)
          Returns a substring from within a string.

        StrTrim (string)
          Trims leading and trailing blanks from a string.

        StrUpper (string)
          Converts a string to all upper-case characters.


                                                                       35

        WINBATCH LANGUAGE


        Arithmetic Functions

        Abs (number)
          Returns the absolute value of a number.

        Average (num [, num]...)
          Returns the average of a list of integers.

        Max (num [, num]...)
          Determines the highest number in a list.

        Min (num [, num]...)
          Determines the lowest number in a list.

        Random (max)
          Generates a positive random number.


        Clipboard Handling

        ClipAppend (string)
          Appends a string to the end of the Clipboard.

        ClipGet ( )
          Returns the Clipboard contents into a string.

        ClipPut (string)
          Replaces the Clipboard contents with a string.


        System Control

        Call (filename.wbt, parameters)
          Calls another WBT file as a subroutine.

        CallExt (filename.wbt, parameters)
          Calls another WBT file as a separate subprogram.

        DateTime ( )
          Returns the current date and time.

        Debug (mode)
          Turns Debug mode on or off.

        Delay (seconds)
          Pauses batch file execution.

        DOSVersion (level)
          Returns the version numbers of the current version of DOS.

        Drop (var [, var]...)
          Deletes variables to recover their memory.

        EndSession ( )
          Ends the current Windows session.

        Environment (env-variable)
          Returns the value of a DOS environment variable.

        ErrorMode (mode)
          Sets what happens in the event of an error.
        36

                                                        WINBATCH LANGUAGE

        Exclusive (mode)
          Controls whether or not other Windows program will get any
          time to execute.

        Execute statement
          Directly executes a WinBatch statement.

        Exit
          Exits the current batch file's operation.

        Goto label
          Changes the flow of control in a batch file.

        If ... Then
          Conditionally performs a function.

        IgnoreInput (mode)
          Turns off hardware input to windows.

        IniRead (section, keyname, default)
          Reads a string from the win.ini file.

        IniReadPvt (section, keyname, default, filename)
          For reading private ini files.

        IniWrite (section, keyname, string)
          Writes a string to the win.ini file.

        IniWritePvt (section, keyname, data, filename)
          For writing private ini files.

        IsDefined (variable)
          Determines if a variable is currently defined.

        IsKeyDown (key-codes)
          Tells about keys/mouse.

        IsLicensed ( )
          Tells if WinBatch is licensed.

        LastError ( )
          Returns the last error encountered.

        Return ( )
          Used to return from a Call or a CallExt to the calling
          program.

        SendKey (character-codes)
          Sends Keystrokes to the active application.

        SKDebug (mode)
          Controls how SendKey works

        Version ( )
          Returns the version of WinBatch currently running.

        WinVersion (level)
          Gets the version of Windows that is currently running.

        Yield
          Pauses batch file processing so other applications can process
          some messages.
                                                                       37

                                                   WBL FUNCTION REFERENCE




                             WBL FUNCTION REFERENCE




        Introduction

        WinBatch gives you almost a hundred functions and control
        statements, which we describe in detail in this section.
        We use a shorthand notation to indicate the syntax of the
        functions.

        Function names and other actual characters you type are in
        boldface.  Optional parameters are enclosed in square brackets "[
        ]".  When a function takes a variable number of parameters, the
        variable parts will be followed by ellipses ("...").

        Take for example string concatenation:

        StrCat (string[, string]...)

        This says that the StrCat function takes at least one string
        parameter.  Optionally you can specify more strings to
        concatenate.  If you do, you must separate the strings with
        commas.

        For each function and control statement, we show you the Syntax,
        describe the Parameters (if any), the value it Returns (if any),
        a description of the function, any nonfatal Errors specific to
        the function, Example code (shown in courier type), and related
        functions you may want to See Also.


























                                                                       39

        WBL FUNCTION REFERENCE






        Abs

        Returns the magnitude of the argument.

        Syntax:
          Abs (integer)

        Parameters:
          integer = integer whose absolute value is desired.

        Returns:
          (integer) absolute value of argument.

        Example:
          DY = abs(y1 - y2)
          Message("Years", "There are %DY% years 'twixt %y1% and %y2%")

        See Also:
          Average, Max, Min



        AskLine

        Prompts the user for one line of input.

        Syntax:
          AskLine (title, prompt, default)

        Parameters:
          "title" = title of the dialog box.
          "prompt" =   question to be put to the user.
          "default" =  default answer.

        Returns:
          (string)  user response.

        Use this command to query the user for a line of data.  The
        entire user response will be returned if the user presses the OK
        button or the Enter key.  If they press Cancel, the batch file
        processing is canceled.

        Example:
          Name = AskLine("Dessert", "Please enter your name", "")
          Dsrt = AskLine("Dessert", "Favorite dessert?", "Ice Cream")
          message(strcat(Name,"'s dessert is "), Dsrt)

        See Also:
          AskYesNo, Display, ItemSelect, Message, Pause, TextBox








        40

                                                   WBL FUNCTION REFERENCE



        AskYesNo

        Prompts the user for a YES or NO answer.

        Syntax:
          AskYesNo (title, question)

        Parameters
          "title" = title of the question box.
          "question" = question to be put to the user.

        Returns:
          (integer) @YES or @NO, depending on the button pressed.

        This command displays a message box with three pushbuttons - Yes,
        No, and Cancel.  If the user presses Cancel, the current batch
        file is ended so there is no return value.

        Example:
          q = AskYesNo('Testing', 'Please press "YES"')
          If q == @YES Then Exit
          Display(3, 'ERROR', 'I said press "YES"')

        See Also:
          AskLine, Display, ItemSelect, Message, Pause, TextBox



        Average

        Provides the integer average of the arguments.

        Syntax:
          Average (integer [, integer]...)

        Parameters:
          integer = integers to get the average of.

        Returns:
          (integer) average of the arguments.

        Use this command to compute the average of a series of numbers.
        This function returns an integer value, so there can be some
        rounding error involved.

        Errors:
          2060 "Average function syntax error"

        Example:
          Ave = Average(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
          Message("The average is", Ave)

        See Also:
          Abs, Max, Min




                                                                       41

        WBL FUNCTION REFERENCE



        Beep

        Beeps once.

        Syntax:
          Beep

        Use this command to produce a short beep, generally to alert the
        user to an error situation.

        Example:
          Beep
          Pause("WARNING!!!", "You are about to destroy data!")



        Call

        Calls another WBT file as a subroutine.

        Syntax:
          Call (filename.wbt, parameters)

        Parameters:
          "filename.wbt" =  the WBT file you are calling.  The extension
                    is required.
          "parameters" = the parameters to pass to the file, if any, in
                    the form "p1 p2 p3  ... pn".

        Returns:
          (integer) always @FALSE.

        Can pass parameters.  All variables are common (global) between
        the calling and the callee WBT file.

        Example:
          Call("chk-nam.wbt", "Susie")

        See Also:
          CallExt



        CallExt

        Calls another WBT file as a separate subprogram.

        Syntax:
          Callext (filename.wbt, parameters)

        Parameters:
          "filename.wbt" =  the WBT file you are calling.  The extension
                    is required.
          "parameters" = the parameters to pass to the file, if any, in
                    the form "p1 p2 p3  ... pn".




        42

                                                   WBL FUNCTION REFERENCE



        Returns:
          (integer) always @FALSE.

        Can pass parameters to the file.  No return value possible.  All
        variables are different.

        Example:
          CallExt("Chk-Num.wbt", "987 234 929")

        See Also:
          Call



        Char2Num

        Converts the first character of a string to its numeric
        equivalent.

        Syntax:
          Char2Num (string)

        Parameters:
          "string" =   any text string.  Only the first character will be
                    converted.

        Returns:
          (integer) ANSI character code.

        This function returns the 8-bit ANSI code corresponding to the
        first character of the string parameter.

        Note:  For the commonly-used characters (with codes below 128),
        ANSI and ASCII characters are identical.

        Example:
          ; Show the hex equivalent of entered character
          InpChar = AskLine("ANSI Equivalents", "Char:", "")
          Ansi = strsub(InpChar, 1, 1)
          AnsiEquiv = Char2Num(InpChar)
          Message("ANSI Codes", "%Ansi% => %AnsiEquiv%")

        See Also:
          Num2Char



        ClipAppend

        Appends a string to the Clipboard.

        Syntax:
          ClipAppend (string)

        Parameters:
          "string" =   text string to add to Clipboard.




                                                                       43

        WBL FUNCTION REFERENCE



        Returns:
          (integer) @TRUE if string was appended;
                    @FALSE if Clipboard ran out of memory.

        Use this command to append a string to the Windows Clipboard.
        The Clipboard must either contain text data or be empty for this
        command to succeed.

        Example:
          ; The code below will append 2 copies of the
          ; Clipboard contents back to the Clipboard, resulting
          ; in 3 copies of the original contents with a CR/LF
          ; between each copy.
          a = clipget()
          crlf = strcat(num2char(13), num2char(10))
          clipappend(crlf)
          clipappend(a)
          clipappend(crlf)
          clipappend(a)

        See Also:
          ClipGet, ClipPut



        ClipGet

        Returns the contents of the Clipboard.

        Syntax:
          ClipGet ( )

        Returns:
          (string)  clipboard contents.

        Use this command to copy text from the Windows Clipboard into a
        string variable.

        Note:  If the Clipboard contains an excessively large string a
        (fatal) out of memory error may occur.

        Example:
          ; The code below will convert Clipboard contents to
          ; uppercase
          clipput(strupper(clipget()))
          a = clipget()
          message("UPPERCASE Clipboard Contents", a)

        See Also:
          ClipAppend, ClipPut









        44

                                                   WBL FUNCTION REFERENCE



        ClipPut

        Copies a string to the clipboard.

        Syntax:
          ClipPut (string)

        Parameters:
          "string" =   any text string.

        Returns:
          (integer) @TRUE if string was copied;
                    @FALSE if clipboard ran out of memory.

        Use this command to copy a string to the Windows Clipboard.  The
        previous Clipboard contents will be lost.

        Example:
          ; The code below will convert Clipboard contents to
          ; lowercase
          clipput(strlower(clipget()))
          a = clipget ()
          message("lowercase Clipboard Contents", a)

        See Also:
          ClipAppend, ClipGet



        DateTime

        Provides the current Date and time.

        Syntax:
          DateTime ( )

        Returns:
          (string)  Today's Date and time

        This function will return the current date and time in a pre-
        formatted string.  The format it is returned in depends on how it
        is set up in the international section of the WIN.INI file:
        ddd mm:dd:yy hh:mm:ss XX
        ddd dd:mm:yy hh:mm:ss XX
        ddd yy:mm:dd hh:mm:ss XX

        Where
          ddd is day of the week (e.g. Mon)
          mm  is the month (e.g. 10)
          dd  is the day of the month (e.g. 23)
          yy  is the year (e.g. 90)
          hh  is the hours
          mm  is the minutes
          ss  is the seconds
          XX  is the Day/Night code (e.g. AM or PM)

        Note:  Windows provides even more formatting options than this.


                                                                       45

        WBL FUNCTION REFERENCE



        The WIN.INI file will be examined to determine which format to
        use.  You can adjust the WIN.INI file via the International
        section of the Control Panel if the format isn't what you prefer.

        Example:
          ; assuming the current standard is U.S.
          ; (i.e. day  dd/mm/yy hh:mm:ss AM):
          Message("Current Date & Time", DateTime())



        Debug

        Controls the debug mode.

        Syntax:
          Debug (mode)

        Parameters:
          mode =    @ON or @OFF

        Returns:
          (integer) Previous Debug mode

        Use this command to turn the debug mode on or off.  The default
        is @OFF.

        When Debug mode is on, WinBatch will display the command just
        executed, its result (if any), any error conditions, and the next
        command to execute.

        The commands are displayed in a special dialog box.  As you can
        see in the Example section following, the dialog box gives the
        user four options:  Next, Run, Cancel and Show Var.
        Next executes the next statement and remains in debug mode.

        Run exits debug mode and runs the rest of the program normally.
        Cancel terminates the current batch file.

        Show Var displays the contents of a variable whose name the user
        entered in the edit box.

        Example:
          ; Debug example
          Debug(@ON)
          a = 6
          q = AskYesNo("Testing Debug Mode", "Is the Pope Catholic")
          Debug(@OFF)
          b = a + 4

        See Also:
          ErrorMode, LastError







        46

                                                   WBL FUNCTION REFERENCE



        Delay

        Pauses execution a specified amount of time.

        Syntax:
          Delay (seconds)

        Parameters:
          seconds = number of seconds to delay (2 - 15)

        Returns:
          (integer) always @TRUE

        Seconds must be between 2 and 15. Smaller or larger numbers will
        be adjusted accordingly.

        Example:
          Message("Wait", "About 15 seconds")
          Delay(15)
          Message("Hi", "I'm Baaaaaaack")

        See Also:
          Yield






        DirChange

        Changes the current directory.  Can also log a new drive.

        Syntax:
          DirChange ([d:]path)

        Parameters:
          "[d:]" =  an optional disk drive to log onto.
          "path" =  the desired path.

        Returns:
          (integer) @TRUE if directory was changed;
                    @FALSE if the path could not be found.

        Use this command to change the current working directory to
        another directory, either on the same or a different disk drive.



                                                                       47

        WBL FUNCTION REFERENCE



        Errors:
          1031 "DirChange: Dir not found/changed"

        Example:
          DirChange("c:\")
          textbox("This is your CONFIG.SYS file", "config.sys")

        See Also:
          DirGet, DirHome, LogDisk



        DirGet

        Gets the Current Working Directory.

        Syntax:
          DirGet ( )

        Returns:
          (string) =   Current Working Directory.

        Use this command to determine which directory we are currently
        in.  It's especially useful when changing drives or directories
        temporarily.

        Example:
          ; Get, then restore current working directory
          OrigDir = DirGet()
          DirChange("c:\")
          FileCopy("config.sys", "%OrigDir%xxxtemp.xyz", @FALSE)
          DirChange(OrigDir)

        See Also:
          DirHome



        DirHome

        Returns directory containing the WinBatch executable files.

        Syntax:
          DirHome ( )

        Returns:
          (string)  pathname of the home directory.

        Use this command to determine the location of WINBATCH.EXE.

        Example:
          a = DirHome()
          Message("WinBatch Executable is in ", a)







        48

                                                   WBL FUNCTION REFERENCE



        See Also:
          DirGet



        DirItemize

        Returns a space-delimited list of directories.

        Syntax:
          DirItemize (dir-list)

        Parameters:
          "dir-list" = a string containing a set of subdirectory names,
                    which may be wildcarded.
        Returns:
          (string)  list of directories.

        This function compiles a list of subdirectories and separates the
        names with spaces.

        This is especially useful in conjunction with the ItemSelect
        function, which enables the user to choose an item from such a
        space-delimited list.
        DirItemize("*.*") returns all dirs

        Example:
          ;Verify directory selection:
          a = DirItemize("")
          ItemSelect("Directories", a, " ")

        See Also:
          FileItemize, WinItemize, ItemSelect



        DirMake

        Creates a new directory.

        Syntax:
          DirMake ([d:]path)

        Parameters:
          "[d:]" =  the desired disk drive.
          "path" =  the path to create.

        Returns:
          (integer) @TRUE if the directory was successfully created;
                    @FALSE if it wasn't.

        Use this command to create a new directory.








                                                                       49

        WBL FUNCTION REFERENCE



        Errors:
          1029 "DirMake: Dir not created"

        Example:
          DirMake("c:\XXXSTUFF")

        See Also:
          DirRemove



        DirRemove

        Removes a directory.

        Syntax:
          DirRemove (dir-list)

        Parameters:
          "dir-list" = a space-delimited list of directory pathnames.

        Returns:
          (integer) @TRUE if the directory was successfully removed;
                    @FALSE if it wasn't.

        Use this command to delete directories.  You can delete one or
        more at a time by separating directory names with spaces.  You
        cannot, however, use wildcards.

        Errors:
          1030 "DirRemove: Dir not removed"

        Examples:
          DirRemove("c:\XXXSTUFF")
          DirRemove("tempdir1 tempdir2 tempdir3")

        See Also:
          DirMake



        DiskFree

        Finds the total space available on a group of drives.

        Syntax:
          DiskFree (drive-list)

        Parameters:
          "drive-list" = at least one drive letter, separated by spaces.

        Returns:
          (integer) the number of bytes available on all the specified
                    drives.

        This function takes a string consisting of drive letters,
        separated by spaces.  Only the first character of each non-blank


        50

                                                   WBL FUNCTION REFERENCE



        group of characters is used to determine the drives, so you can
        use just the drive letters, or add a colon (":"), or add a
        backslash ("\"), or even a whole pathname and still get a
        perfectly valid result.

        Example:
          Size = DiskFree("c d")
          Message("Space Available on C: & D:", Size)

        See Also:
          FileSize



        Display

        Displays a message to the user for a specified time.

        Syntax:
          Display (seconds, title, text)

        Parameters:
          seconds = integer seconds to display the message (1-15).
          "title" = Title of the window to be displayed.
          "text" =  Text of the window to be displayed.

        Returns:
          (integer) always @TRUE.

        Seconds must be between 1 and 15.  Smaller or larger numbers will
        be adjusted accordingly.
        Use this command to display a message for a few seconds, and then
        continue with processing without user input.

        The display box may be prematurely canceled by the user by
        clicking it with a mouse, or hitting any character.

        Example:
          name = askline("Desserts", "Please enter your name", "")
          dsrt = askline("Desserts", "Favorite dessert?", "Ice Cream")
          display(3, "%name%'s Dessert", dsrt)

        See Also:
          Pause, Message



        DOSVersion

        Returns the version numbers of the current version of DOS.

        Syntax:
          DOSVersion (level)

        Parameters:
          level =   @MAJOR or @MINOR.




                                                                       51

        WBL FUNCTION REFERENCE




        @MAJOR returns the integer part (to the left of the decimal).
        @MINOR returns the decimal part (to the right of the decimal).

        Example:
          r = DOSVersion(@MAJOR)
          v = DOSVersion(@MINOR)
          Message("DOS Version", "%r%.%v%")



        Drop

        Removes variables from memory.

        Syntax:
          Drop (var, [var]...)

        Parameters:
          var =     variable names to remove.

        Returns:
          (integer) @TRUE.

        This function removes variables from the language processor's
        variable list, and recovers the memory associated with the
        variable (and possibly related string storage).

        Example:
          A = "A variable"
          B = "Another one"
          Drop(A, B)   ; This removes A and B from memory



        EndSession

        Ends the Windows session.

        Syntax:
          EndSession ( )

        Use this command to end the Windows session.  This command is
        equivalent to closing the Program Manager window.

        Example:
          Sure = AskYesNo ("End Session", "You SURE you want to exit
            Windows?")
          If Sure == @No Then Goto Cancel
          EndSession()
          :Cancel
          Message("", "Exit Windows canceled")

        See Also:
          Exit, WinClose, WinCloseNot




        52

                                                   WBL FUNCTION REFERENCE



        Environment

        Gets a DOS environment variable.

        Syntax:
          Environment (env-variable)

        Parameters:
          "env-variable" =  any defined environment variable.

        Returns:
          (string)  environment variable contents.

        Use this command to query the DOS environment.

        Example:
          ; Display the PATH for this DOS session
          CurrPath = Environment("PATH")
          Message("Current DOS Path", CurrPath)

        See Also:
          IniRead, Version, WinVersion



        ErrorMode

        Specifies how to handle errors.

        Syntax:
          ErrorMode (mode)

        Parameters:
          mode =    @CANCEL or @NOTIFY or @OFF.

        Returns:
          (integer) previous error setting.

        Use this command to control the effects of runtime errors.  The
        default is @CANCEL, meaning the execution of the batch file will
        be canceled for any error.

        @CANCEL:  All runtime errors will cause execution to be
        canceled.  The user will be notified which error occurred.

        @NOTIFY:  All runtime errors will be reported to the user, and
        they can choose to continue if it isn't fatal.

        @OFF:  Minor runtime errors will be suppressed. Moderate and
        fatal errors will be reported to the user.  User has the option
        of continuing if the error is not fatal.
        In general we suggest the normal state of the program should be
        ErrorMode(@CANCEL), especially if you are writing a batch file
        for others to use.  You can always suppress errors you expect
        will occur and then re-enable ErrorMode (@CANCEL).




                                                                       53

        WBL FUNCTION REFERENCE



        Example:
          ; Delete xxxtest.xyz.
          ; If file doesn't exist, continue execution; don't stop
          prevmode = ErrorMode(@OFF)
          FileDelete("c:\xxxtest.xyz")
          ErrorMode(prevmode)

        See Also:
          Debug, LastError



        Execute

        Executes a statement in a protected environment.  Any errors
        encountered are recoverable.

        Syntax:
          Execute statement

        Parameters:
          "statement" =  is (hopefully) an executable statement.

        Use this command to execute computed or user-entered statements.
        Due to the built-in error recovery associated with the Execute
        statement, it is ideal for interactive execution of user-entered
        commands.

        Note the Execute statement doesn't operate on a string per se,
        but rather on a direct statement.  If you want to put a code
        segment into a string variable you must use the substitution
        feature of the language, as in the example below.

        Example:
          cmd = ""
          cmd = AskLine("WBL Interactive", "Command:", cmd)
          execute %cmd%



        Exit

        Terminates the batch file being interpreted.

        Syntax:
          Exit

        Use this command to prematurely exit a batch file process.  An
        exit is implied at the end of each batch file.

        Example:
          a = 100
          message("The value of a is", a)
          exit






        54

                                                   WBL FUNCTION REFERENCE



        See Also:
          Pause



        Exclusive

        Controls whether or not other Windows program will get any time
        to execute.

        Syntax:
          Exclusive (mode)

        Parameters:
          mode =    @ON or @OFF.

        Returns:
          (integer) previous Exclusive mode.

        Exclusive(@ON) runs the fastest but does not allow other Windows
        applications to get much time.  Exclusive(@OFF) runs just a tad
        slower, is the default, and is nicely mannered to other
        applications.

        Example:
          ; We want Excel to get top processing priority
          RunZoom("excel.exe, "")
          Exclusive(@ON)
          ; When we're done with Excel, return to default mode
          WinWaitClose ("Microsoft Excel")
          Exclusive(@OFF)



        FileClose

        Closes a file.

        Syntax:
          Fileclose (filehandle)

        Parameters:
          filehandle = same integer that was returned by FileOpen.

        Returns:
          (integer) always 0.

        Example:
          ; the hard way to copy an ascii file
          old = FileOpen("config.sys", "READ")
          new = FileOpen("sample.txt", "WRITE")
          :top
          x = FileRead(old)
          If x != "*EOF*" Then FileWrite(new, x)
          If x != "*EOF*" Then Goto top





                                                                       55

        WBL FUNCTION REFERENCE



          FileClose(new)
          FileClose(old)



        FileCopy

        Copies files.

        Syntax:
          FileCopy (source-list, destination, warning)

        Parameters:
          "source-list" =   a string containing one or more filenames,
                    which may be wildcarded.
          "destination" =   target file name.

          warning = @TRUE if you want a warning before
                    overwriting existing files;
                    @FALSE if no warning desired.

        Returns:
          (integer)    @TRUE if all files were copied successfully;
                       @FALSE if at least one file wasn't copied.

        Use this command to copy an individual file, a group of files
        using wildcards, or several groups of files by separating the
        names with spaces.
        You can also copy files to any COM or LPT device.

        "Source-list" may contain * and ? wildcards.  "Destination" may
        contain the * wildcard only.

        Errors:
          1006 "File Copy/Move: No matching files found"
          2002 "File Copy/Move: 'From' file illegal"
          2003 "File Copy/Move: 'To'   file illegal"
          2004 "File Copy/Move: Cannot copy/move wildcards into fixed
                root"
          2005 "File Copy/Move: Cannot copy/move wildcards into fixed
                extension"
          3118 "FileCopyMove: Destination file same as source"

        Examples:
          FileCopy("c:\config.sys", "d:", @FALSE)
          FileCopy("c:\*.sys", "d:devices\*.sys", @TRUE)
          FileCopy("c:\config.sys", "LPT1:", @FALSE)

        See Also:
          FileDelete, FileExist, FileLocate, FileMove, FileRename



        FileDelete

        Deletes files.



        56

                                                   WBL FUNCTION REFERENCE



        Syntax:
          FileDelete (file-list)

        Parameters:
          "file-list" =  a string containing one or more filenames,
                    which may be wildcarded.
        Returns:
          (integer) @TRUE if all the files were deleted;
                    @FALSE if a file didn't exist or is marked with the
                    READ-ONLY attribute.

        Use this command to delete an individual file, a group of files
        using wildcards, or several groups of files by separating the
        names with spaces.

        Errors:
          1017 "File Delete: No matching files found"
          1018 "File Delete: Delete Failed"
          2016 "File Delete: File name illegal"

        Example:
          WasDeleted = FileDelete("badfile")

        See Also:
          FileExist, FileLocate, FileMove, FileRename



        FileExist

        Tests for the existence of files.

        Syntax:
          FileExist (filename)

        Parameters:
          "filename" = either a fully qualified filename with drive and
                    path, or just a filename and extension.
        Returns:
          (integer) @TRUE if the file exists;
                    @FALSE if it doesn't or if the pathname is invalid.

        This statement is used to test whether or not a specified file
        exists.

        If a fully qualified file name is used only the specified drive
        and directory will be checked for the desired file.  If only the
        root and extension are specified, then all the directories in the
        DOS PATH statement will be searched for the desired file.










                                                                       57

        WBL FUNCTION REFERENCE



        Example:
          ; check for file in current directory
          fex = FileExist(StrCat(DirGet(), "myfile.txt"))
          tex = StrSub("NOT", 1, StrLen("NOT") * fex)
          Message("MyFile.Txt"," Is %tex%in the current directory")
          ; check for file in someplace along path
          fex = FileExist("myfile.txt")
          tex = StrSub("NOT", 1, StrLen("NOT") * fex)
          Message("MyFile.Txt", " Is %tex% in the DOS path")

        See Also:
          FileLocate



        FileExtension

        Returns extension of file.

        Syntax:
          FileExtension (filename)

        Parameters:
          "filename" = [optional path]complete file name, with extension.

        FileExtension parses the passed filename and returns the
        extension part of the filename.

        Example:
          ; prevent the user from editing a COM or EXE file
          allfiles = FileItemize("*.*")
          editfile = ItemSelect("Select a file to edit", allfiles, " ")
          ext = FileExtension(editfile)
          If (ext == "com") || (ext == "exe") Then Goto noedit
          run("notepad.exe", editfile)
          exit
          :noedit
          Message ("Sorry", "You may not edit a program file")



        FileItemize

        Returns a space-delimited list of files.

        Syntax:
          FileItemize (file-list)

        Parameters:
          "file-list" =  a string containing a list of filenames, which
                    may be wildcarded.

        Returns:
          (string)  space-delimited list of files.




        58

                                                   WBL FUNCTION REFERENCE




        This function compiles a list of filenames and separates the
        names with spaces.

        FileItemize("*.BAK") ;returns all BAK's
        FileItemize("*.ARC *.ZIP *.LZH") ;returns list of compressed
        files

        This is especially useful in conjunction with the ItemSelect
        function, which enables the user to choose an item from such a
        space-delimited list.

        Examples:
          ; Get which .INI file to edit
          ifiles = FileItemize("c:\windows\*.ini")
          ifile = ItemSelect(".INI Files", ifiles, " ")
          RunZoom("notepad", ifile)
          Drop(ifiles, ifile)

        See Also:
          DirItemize, WinItemize, ItemSelect



        FileLocate

        Finds file in current directory or along the DOS PATH.

        Syntax:
          FileLocate (filename)

        Parameters:
          "filename" = root name, ".", and an extension.

        Returns:
          (string)  fully qualified path name.

        This function is used to obtain the fully qualified path name of
        a file.  The current directory is checked first, and if the file
        is not found the DOS path is searched.  This function returns the
        first occurrence of the file.

        Example:
          ; Edit WIN.INI
          winini = FileLocate("win.ini")
          If winini == "" Then Goto notfound
          Run("notepad.exe", winini)
          Exit
          :notfound
          Message("???", "WIN.INI not found")

        See Also:
          FileExist






                                                                       59

        WBL FUNCTION REFERENCE



        FileMove

        Moves files.

        Syntax:
          FileMove (source-list, destination, warning)

        Parameters:
          "source-list" =   one or more filenames separated by spaces.
          "destination" =   target filename.
          warning =         @TRUE if you want a warning before
                            overwriting existing files; @FALSE if no
                            warning desired.

        Returns:
          (integer) @TRUE if the file was moved;
                    @FALSE if the source file was not found or had the
                    READ-ONLY attribute, or the target filename is
                    invalid.

        Use this command to move an individual file, a group of files
        using wildcards, or several groups of files by separating the
        names with spaces.

        You can also move files to another drive, or to any COM or LPT
        device.

        "Source-list" may contain * and ? wildcards.  "Destination" may
        contain the * wildcard only.

        Errors:
          1006 "File Copy/Move: No matching files found"
          2002 "File Copy/Move: 'From' file illegal"
          2003 "File Copy/Move: 'To'   file illegal"
          2004 "File Copy/Move: Cannot copy/move wildcards into fixed
                root"
          2005 "File Copy/Move: Cannot copy/move wildcards into fixed
                extension"
          2007 "File Move: Unable to rename source file"
          2015 "File Move:  Unable to remove source file"

        Example:
          FileMove("c:\config.sys", "d:", @FALSE)
          FileMove("c:\*.sys", "d:*.sys", @TRUE)

        See Also:
          FileCopy, FileDelete, FileExist, FileLocate, FileRename



        FileOpen

        Opens a STANDARD ASCII (only) file for reading or writing.

        Syntax:
          Fileopen ( filename, open-type)



        60

                                                   WBL FUNCTION REFERENCE



        Parameters:
          "filename" = name of the file to open.
          open-type =  READ or WRITE.

        Returns:
          (special integer) filehandle

        The filehandle returned by the FileOpen function is subsequently
        used by the FileRead,FileWrite and FileClose functions.

        Examples:

        To open for reading:
          FileOpen("stuff.txt", "READ")

        To open for writing:
          FileOpen("stuff.txt", "WRITE")



        FilePath

        Returns path of file.

        Syntax:
          FilePath (filename)

        Parameters:
          "filename" = fully qualified file name, including path.

        FilePath parses the passed filename and returns the drive and
        path of the file specification, if any.

        Example:
          coms = environment("comspec")
          compath = FilePath(coms)
          Message("", "Your command processor is located in the
            %compath% directory")



        FileRead

        Reads data from a file.

        Syntax:
          Fileread(filehandle)

        Parameters:
          filehandle = same integer that was returned by FileOpen.

        Returns:
          (string)  line of data read from file.

        At EOF the string *EOF* will be returned.

        Example:
          handle = FileOpen("autoexec.bat", "READ")

                                                                       61

        WBL FUNCTION REFERENCE



          :top
          line = FileRead(handle)
          Display(4, "AUTOEXEC DATA", line)
          If line != "*EOF*" Then Goto top
          FileClose(handle)



        FileRename

        Renames files.

        Syntax:
          FileRename (source-list, destination)

        Parameters:
          "source-list" =   one or more filenames separated by spaces.
          "destination" =   target filename.

        Returns:
          (integer) @TRUE if the file was renamed;
                    @FALSE if the source file was not found or had the
                    READ-ONLY attribute, or the target filename is
                    invalid.

        Use this command to rename an individual file, a group of files
        using wildcards, or several groups of files by separating the
        names with spaces.
        Note: Unlike FileMove, you cannot make a file change its resident
        disk drive with FileRename.

        "Source-list" may contain * and ? wildcards.  "Destination" may
        contain the * wildcard only.

        Errors:
          1024 "File Rename: No matching files found"
          1025 "File Rename: Rename failed"
          2019 "File Rename: 'From' file illegal"
          2020 "File Rename: 'To' file illegal"
          2021 "File Rename: Attempt to rename across drive boundary. -
                Use MOVE instead."
          2022 "File Rename: Cannot rename wildcards into a fixed
                filename root"
          2023 "File Rename: Cannot rename wildcards into a fixed
                filename extension"

        Example:
          FileRename("c:\config.sys", "config.old")
          FileRename("c:\*.txt", "*.bak")

        See Also:
          FileCopy, FileExist, FileLocate, FileMove








        62

                                                   WBL FUNCTION REFERENCE



        FileRoot

        Returns root of file.

        Syntax:
          FileRoot (filename)

        Parameters:
          "filename" = [optional path]complete file name, with extension.

        FileRoot parses the passed filename and returns the root part of
        the filename.

        Example:
          allfiles = FileItemize("*.*")
          editfile = ItemSelect("Select a file to edit", allfiles, " ")
          root = FileRoot(editfile)
          ext = FileExtension(editfile)
          lowerext = StrLower(ext)
          nicefile = StrCat(root, ".", lowerext)
          Message("", "You are about to edit %nicefile%.")
          run("notepad.exe", editfile)



        FileSize

        Finds the total size of a group of files.

        Syntax:
          FileSize (file-list)

        Parameters:
          "file-list" =  zero or more filenames, separated by spaces.

        Returns:
          (integer) total bytes taken up by the specified files.

        This function returns the total size of the specified files.
        Note it doesn't handle wildcarded filenames.  You can, however,
        use FileItemize on a wildcarded filename and use the resulting
        string with as a FileSize parameter.

        Errors:
          3112 "FileSize:  File Not Found"

        Example:
          size = FileSize(FileItemize(""))
          Message("Size of Highlighted Files", size)

        See Also:
          DiskFree








                                                                       63

        WBL FUNCTION REFERENCE



        FileWrite

        Writes data to a file.

        Syntax:
          Filewrite(filehandle,output-data)

        Parameters:
          filehandle = same integer that was returned by FileOpen.
          "output-data" =   data to write to file.

        Returns:
          (integer) always 0.

        Example:
          handle = FileOpen("stuff.txt", "WRITE")
          FileWrite(handle, "Gobbledygook")
          FileClose(handle)



        Goto

        Changes the flow of control in a batch file.

        Syntax:
          Goto label

        Parameters:
          "label" = user-defined identifier.

        Note:  labels begin with a colon (:)

        Example:
          a = 0
          :loop
          If A > 5 Then Goto next
          Message("A is now", a)
          a = a + 1
          Goto loop
          :next
          Message("DONE", "Loop Exited")



        If_Then

        Conditionally performs a function.

        Syntax:
          If condition Then statement

        If the condition following the If keyword is true, the statement
        following the Then keyword is executed.  If the condition
        following the If keyword is false, the statement following the
        Then keyword is ignored.



        64

                                                   WBL FUNCTION REFERENCE


        Example:
          If a > 5 Then Message("Hello", "A GT 5")


        IgnoreInput

        Turns off hardware input to windows.

        Syntax:
          IgnoreInput(mode)

        Parameters:
          mode =    @TRUE or @FALSE.

        Returns:
          (integer) previous IgnoreInput mode.

        IgnoreInput causes mouse movements, clicks and keyboard entry to
        be completely ignored.  Good for self-running demos.

        Warning: If you are not careful with the use of IgnoreInput, you
        can hang your machine.

        Example:
          username = AskLine("Hello", "Please enter your name","")
          IgnoreInput(@TRUE)
          Call("demo.wbt", "username")
          IgnoreInput(@FALSE)

        IniRead

        Reads data from the WIN.INI file.

        Syntax:
          IniRead (section, keyname, default)

        Parameters:
          "section" =  the major heading to read the data from.
          "keyname =   the name of the item to read.
          "default" =  string to return if the desired item is not found.

        Returns:
          (string)  data from WIN.INI file.

        This command allows a program to read data from the WIN.INI file.
        The WIN.INI file has the form:

          [section]
          keyname=settings

        Most of the entries in WIN.INI are set from the Windows Control
        Panel program, but individual applications can also use it to
        store option settings in their own sections.
                                                                       65

        WBL FUNCTION REFERENCE



        Example:
          ; Find the default output device:
          a = IniRead("windows", "device", "No Default")
          Message("Default Output Device", a)

        See Also:
          Environment, IniWrite



        IniReadPvt

        For reading private ini files.

        Syntax:
          IniReadPvt (section, keyname, default,filename)

        Parameters:
          "section" =  the major heading to read the data from.
          "keyname =   the name of the item to read.
          "default" =  string to return if the desired item is not found.
          "filename" = name of the INI file.

        Returns:
          (string)  data from the INI file.

        Looks up a value in the "filename" ini file.  If the value is not
        found, the "default" will be returned.

        Example:
        Given the following segment from WB.INI

          [Main]
          Lang=German

        The statement:

          IniReadPvt("Main", "Lang", "English", "WB.INI")

        would return "German"



        IniWrite

        Writes data to the WIN.INI file.

        Syntax:
          IniWrite (section, keyname, data)

        Parameters:
          "section" =  major heading to write the data to.
          "keyname =   name of the data item to write.
          "data" =  string to write to the WIN.INI file.

        Returns:
          (integer) always @TRUE.

        66

                                                   WBL FUNCTION REFERENCE




        This command allows a program to write data to the WIN.INI file.
        The "section" is added to the file if it doesn't already exist.

        Example:
          ; Change the list of pgms to load upon Windows startup:
          loadprogs = IniRead("windows", "load", "")
          newprogs = AskLine("Add Pgm To LOAD= Line", "Add:", loadprogs)
          IniWrite("windows", "load", newprogs)

        See Also:
          IniRead



        IniWritePvt

        For writing private ini files.

        Syntax:
          IniWritePvt (section, keyname, data, filename)

        Parameters:
          "section" =  major heading to write the data to.
          "keyname =   name of the data item to write.
          "data" =  string to write to the INI file.
          "filename" = name of the INI file.

        Writes a value in the "filename" ini file.

        Example:
        The statement:

          IniWritePvt("Main", "Lang", "French, "WB.INI")

        would create the following entry in WB.INI:

          [Main]
          Lang=French



        IsDefined

        Determines if a variable name is currently defined.

        Syntax:
          IsDefined (var)

        Parameters:
          "var" =   a variable name.

        Returns:
          (integer) @YES if the variable is currently defined;
                    @NO if it was never defined or has been dropped.





                                                                       67

        WBL FUNCTION REFERENCE



        A variable is defined the first time it appears at the left of an
        equal sign in a statement.  It stays defined until it is
        explicitly Dropped.

        Example:
          def = IsDefined(thisvar)
          If def == @FALSE Then Message("ERROR!", "Variable not
            defined")

        See Also:
          Drop



        IsKeyDown

        Tells about keys/mouse.

        Syntax:
          IsKeyDown(keycodes)

        Parameters:
          keycodes =   @SHIFT and/or @CTRL

        Returns:
          (integer) @YES if the key is down.
                    @NO if the key is not down.

        Determines if the SHIFT key or the CTRL key is currently down.
        Note: Right mouse button is the same as SHIFT, and  Middle mouse
        button is the same as CTRL.

        Examples:

          IsKeyDown(@SHIFT)
          IsKeyDown(@CTRL)
          IsKeyDown(@CTRL | @SHIFT)
          IsKeyDown(@CTRL & @SHIFT)



        IsLicensed

        Tells if WinBatch is licensed.

        Syntax:
          IsLicensed()

        Returns:
          (integer) @YES if current version of WinBatch is licensed.
                    @NO if current version of WinBatch is not licensed.

        Returns whether or not the current version of WinBatch is a
        licensed copy or not.






        68

                                                   WBL FUNCTION REFERENCE



        Example:
          IsLicensed()



        IsNumber

        Determines whether a variable contains a valid number.

        Syntax:
          IsNumber (string)

        Parameters:
          "string" =   string to test to see if it represents a valid
                       number.

        Returns:
          (integer) @YES if it contains a valid number;
                    @NO if it doesn't.

        This function determines if a string variable contains a valid
        integer.  Useful for checking user input prior to using it in
        computations.

        Example:
          a = AskLine("ISNUMBER", "Enter a number", "0")
          If IsNumber(a) == @NO Then Message("", "You didn't enter a
            number")

        See Also:
          Abs, Char2Num



        ItemSelect

        Allows the user to choose an item from a listbox.

        Syntax:
          ItemSelect (title, list, delimiter)

        Parameters:
          "title" = the title of dialog box to display.
          "list" =  a string containing a list of items to choose from.
          "delimiter" =  a string containing the character to act as
                    delimiter between items in the list.

        Returns:
          (string)  the selected item.

        This function displays a dialog box with a listbox inside.  This
        listbox is filled with a list of items taken from a string you
        provide to the function.
        Each item in the string must be separated ("delimited") by a
        character, which you also pass to the function.




                                                                       69

        WBL FUNCTION REFERENCE



        The user selects one of the items by either doubleclicking on it,
        or single-clicking and pressing OK.  The item is returned as a
        string.

        If you create the list with the FileItemize or DirItemize
        functions you will be using a space-delimited list.  WinItemize,
        however, creates a tab-delimited list of window titles since
        titles can have embedded blanks.

        Example:
          Files = FileItemize("*.bmp")
          thefile = ItemSelect("Bitmap Files", Files, " ")
          Run("pbrush.exe", thefile)

        See Also:
          AskYesNo, Display,  DirItemize, FileItemize, WinItemize,
          Message, Pause, TextBox



        LastError

        Returns the most-recent error encountered during the current
        batch file.

        Syntax:
          LastError ( )

        Returns:
          (integer) most-recent WBL error code encountered.

        WBL errors are numbered according to their severity.  "Minor"
        errors go from 1000 through 1999.  Moderate errors are 2000
        through 2999.  Fatal errors are numbered 3000 to 3999.
        Depending on which error mode is active when an error occurs, you
        may not get a chance to check the error code.  See ErrorMode for
        a discussion of default error handling.

        Don't bother checking for "fatal" error codes.  When a fatal
        error occurs, the batch file is canceled before the next WBL
        statement gets to execute (regardless of which error mode is
        active).

        Calling LastError itself resets the last error indicator back to
        zero.

        A full listing of possible errors you can encounter in processing
        a batch file is in Appendix B - Errors.

        Example:
          ErrorMode(@OFF)
          FileCopy("data.dat", "c:\backups", @FALSE)
          ErrorMode(@CANCEL)
          If LastError() == 1006 Then Message("Error", "Please call Tech
            Support at 555-9999.")





        70

                                                   WBL FUNCTION REFERENCE



        See Also:
          Debug, ErrorMode



        LogDisk

        Logs (activates) a disk drive.

        Syntax:
          LogDisk (drive-letter)

        Parameters:
          "drive-letter" =  is the disk drive to log into.

        Returns:
          (integer) @TRUE if the current drive was changed;
                    @FALSE if the drive doesn't exist.

        Use this command to change the logged disk drive.

        This command produces the same effect as if you typed the drive
        name from the DOS command prompt.

        Errors:
          1028 "LogDisk: Requested drive not online"

        Example:
          logdisk("c:")

        See Also:
          DirChange



        Max

        Returns largest number in a list of numbers.

        Syntax:
          Max (integer [, integer]...)

        Parameters:
          integer = number.

        Returns:
          (integer) largest parameter.

        Use this function to determine the largest of a set of numbers.

        Example:
          a = Max(5, -37, 125, 34, 2345, -32767)
          Message("Largest number is", a)

        See Also:
          Abs, Average, Min



                                                                       71

        WBL FUNCTION REFERENCE



        Message

        Displays a message to the user.

        Syntax:
          Message (title, text)

        Parameters:
          "title" = title of the message box.
          "text" =  text to display in the message box.

        Returns:
          (integer) always @TRUE.

        Use this command to display a message to the user.  The user must
        respond by selecting the OK button before processing will
        continue.

        Example:
          Message("GUESSIT", "Pick a number between 1 and 100")
          Message("GUESSIT", "Multiply your number by 2")
          Message("GUESSIT", "Add 34")
          Message("GUESSIT", "Divide by 2")
          Message("GUESSIT", "Subtract your original number")
          Message("GUESSIT", "Your answer is 17")

        See Also:
          Display, Pause



        Min

        Returns lowest number in a list of numbers.

        Syntax:
          Min (integer [, integer]...)

        Parameters:
          integer = any integer number.

        Returns:
          (integer) lowest parameter.

        Use this function to determine the lowest of a set of integers.

        Example:
          a = Min( 5, -37, 125, 34, 2345, -32767)
          Message("Smallest number is", a)

        See Also:
          Abs, Average, Max








        72

                                                   WBL FUNCTION REFERENCE



        Num2Char

        Converts a number to its character equivalent.

        Syntax:
          Num2Char (integer)

        Parameters:
          number =  any number from 0 to 255.

        Returns:
          (string)  one-byte string containing the character the number
                    represents.

        Use this command to convert a number to its ASCII equivalent.

        Example:
          ; Build a variable containing a CRLF combo
          crlf = StrCat(Num2Char(13), Num2Char(10))
          Message("NUM2CHAR", StrCat("line1", crlf, "line2"))

        See Also:
          Char2Num



        ParseData

        Parses the passed string, just like passed parameters are parsed.

        Syntax:
          Parsedata (string)

        Parameters:
          "string" =   string to be parsed.

        Variables show up as param1, param2, etc.  Param0 is the count of
        the number of parameters.

        Example:
          username = AskLine("Hello", "Please enter your name","")
          ParseData(username)

        If the user entered

          Joe Q. User

        ParseData would create the following variables:

             param0 == 3
             param1 == "Joe"
             param2 == "Q."
             param3 == "User"







                                                                       73

        WBL FUNCTION REFERENCE



        Pause

        Provides a message to user.  User may cancel processing.

        Syntax:
          Pause (title, text)

        Parameters:
          "title" = title of pause box.
          "text" =  text of the message to be displayed.

        Returns:
          (integer)    always @TRUE.

        This command displays a message to the user with an exclamation
        point icon.  The user may respond by selecting the OK button, or
        they may cancel the processing by selecting CANCEL.

        The Pause command is similar to the Message command except for
        the addition of the CANCEL button and icon.

        Example:
          Pause("Change Disks", "Insert new disk into Drive A:")

        See Also:
          Display, Message



        Random

        Computes a pseudo-random number.

        Syntax:
          Random (max)

        Parameters:
          max =     largest desired number.

        Returns:
          (integer) unpredictable positive number.

        This function will return a random integer between 0 and "max".

        Example:
          a = Random(79)
          Message("Random number between 0 and 79", a)



        Return

        Used to return from a Call or a CallExt to the calling program.

        Syntax:
          Return



        74

                                                   WBL FUNCTION REFERENCE



        If the program was not called, then an EXIT is assumed.

        Example:
          Display(2, "End of subroutine", "Returning to MAIN.WBT")
          Return



        Run

        Runs a program as a normal window.

        Syntax:
          Run (program-name, parameters)

        Parameters:
          "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT
                    file, or a data file.
          "parameters" = optional parameters as required by the applica-
                    tion.

        Returns:
          (integer) @TRUE if the program was found;
                    @FALSE if it wasn't.

        Use this command to run an application.

        If the drive and path are not part of the program name, the
        current directory will be examined first and then the DOS path
        will be searched to find the desired executable file.

        If the "program-name" doesn't have an extension of .EXE, .COM,
        .PIF, or .BAT, it will be run in accordance with whatever is in
        the [extensions] section of the WIN.INI file.  When this happens,
        any "parameters" you specified are ignored.

        Examples:
          Run("notepad.exe", "abc.txt")
          Run("clock.exe", "")
          Run("paint.exe", "pict.msp")

        See Also:
          RunHide, RunIcon, RunZoom, WinClose, WinWaitClose



        RunHide

        Runs a program as a hidden window.

        Syntax:
          RunHide (program-name, parameters)

        Parameters:
          "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT
                    file, or a data file.
          "parameters" = optional parameters as required by the
                    application.


                                                                       75

        WBL FUNCTION REFERENCE



        Returns:
          (integer) @TRUE if the program was found;
                    @FALSE if it wasn't.

        Use this command to run an application as a hidden window.

        If the drive and path are not part of the program name, the
        current directory will be examined first and then the DOS path
        will be searched to find the desired executable file.

        If the "program-name" doesn't have an extension of .EXE, .COM,
        .PIF, or .BAT, it will be run in accordance with whatever is in
        the [extensions] section of the WIN.INI file.  When this happens,
        any "parameters" you specified are ignored.

        Note:  When this command launches an application it informs it
        that you want it to run as a hidden window.  Whether or not the
        application honors your wish is beyond RunHide's control.

        Examples:
          RunHide("notepad.exe", "abc.txt")
          RunHide("clock.exe", "")
          RunHide("paint.exe", "pict.msp")

        See Also:
          Run, RunIcon, RunZoom, WinHide, WinClose, WinWaitClose



        RunIcon

        Runs a program as an iconic (minimized) window.

        Syntax:
          RunIcon (program-name, parameters)

        Parameters:
          "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT
                    file, or a data file.
          "parameters" = optional parameters as required by the
                    application.
        Returns:
          (integer) @TRUE if the program was found;
                    @FALSE if it wasn't.

        Use this command to run an application as an icon.

        If the drive and path are not part of the program name, the
        current directory will be examined first and then the DOS path
        will be searched to find the desired executable file.

        If the "program-name" doesn't have an extension of .EXE, .COM,
        .PIF, or .BAT, it will be run in accordance with whatever is in
        the [extensions] section of the WIN.INI file.  When this happens,
        any "parameters" you specified are ignored.




        76

                                                   WBL FUNCTION REFERENCE



        Note:  When this command launches an application it merely
        informs it that you want it to begin as an icon.  Whether or not
        the application honors your wish is beyond RunIcon's control.

        Examples:
          RunIcon("notepad.exe", "abc.txt")
          RunIcon("clock.exe", "")
          RunIcon("paint.exe", "pict.msp")

        See Also:
          Run, RunHide, RunZoom, WinIconize, WinClose, WinWaitClose



        RunZoom

        Runs a program as a full-screen (maximized) window.

        Syntax:
          RunZoom (program-name, parameters)

        Parameters:
          "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT
                    file, or a data file.
          "parameters" = optional parameters as required by the
                    application.

        Returns:
          (integer) @TRUE if the program was found;
                    @FALSE if it wasn't.

        Use this command to run an application as a full-screen window.
        If the drive and path are not part of the program name, the
        current directory will be examined first and then the DOS path
        will be searched to find the desired executable file.

        If the "program-name" doesn't have an extension of .EXE, .COM,
        .PIF, or .BAT, it will be run in accordance with whatever is in
        the [extensions] section of the WIN.INI file.  When this happens,
        any "parameters" you specified are ignored.
        Note:  When this command launches an application it merely
        informs it that you want it to be maximized to full-screen.
        Whether or not the application honors your wish is beyond
        RunZoom's control.

        Examples:
          RunZoom("notepad.exe", "abc.txt")
          RunZoom("clock.exe", "")
          RunZoom("paint.exe", "pict.msp")

        See Also:
          Run, RunHide, RunIcon, WinZoom, WinClose, WinWaitClose






                                                                       77

        WBL FUNCTION REFERENCE



        SendKey

        Sends keystrokes to the active application.

        Syntax:
          Sendkey (character-codes)

        Parameters:
          "character-codes" = string of regular and special characters
                    (see below).
        Returns:
          (integer) always 0

        SendKey is used to send keystrokes to the current window, just as
        if they had been entered from the keyboard.  Any alphanumeric
        character may be sent by simply placing the character in the
        string.  In addition, the following special characters may be
        used:

          Backspace {BACKSPACE} or {BS}
          Break     {BREAK}
          Clear     {CLEAR}
          Delete    {DELETE} or {DEL}
          Down Arrow   {DOWN}
          End       {END}
          ENTER     {ENTER} or ~
          Escape    {ESCAPE} or {ESC}
          F1 through F12 {F1} through {F12}
          Help      {HELP}
          Home      {HOME}
          Insert    {INSERT}
          Left Arrow   {LEFT}
          Page Down {PGDN}
          Page Up   {PGUP}
          Print Screen {PRTSC}
          Right Arrow  {RIGHT}
          Space     {SPACE} or {SP}
          Tab       {TAB}
          Up Arrow  {UP}

        To enter an Alt, Control, or Shift key combination, precede the
        desired key with one of the following symbols:

          Alt       !
          Control   ^
          Shift     +

        For example, to enter Alt-S:

          SendKey("!S").

        You may also repeat a key by following it with a space and then
        the total number of repetitions desired.
        For example, to move the cursor down 8 lines:

          SendKey("{DOWN} 8")




        78

                                                   WBL FUNCTION REFERENCE





        Example:
          ; Start Notepad.  Use *.* for filenames
          Run("Notepad.exe", "")
          SendKey("!FO*.*~")

        It is possible to use SendKey to send keystrokes to a DOS
        application, but only if you are running Windows in 386 Enhanced
        mode.  You transfer the keystrokes to the DOS application via the
        clipboard.  For example:

          ; run batch file which starts our editor
          run("edit.bat", "")
          ; wait 15 seconds for editor to load
          Delay(15)
          ; send Alt-F N to the clipboard
          ClipPut("!FN")
          ; paste contents of clipboard to DOS window
          SendKey("!{SP}EP")

        See Also:
          SKDebug



        SKDebug

        Controls how SendKey works

        Syntax:
          Skdebug(mode)

        Parameters:
          mode =    @OFF  Keystrokes sent to application.  No debug file
                    written.  Default mode.
                    @ON  Keystrokes sent to application.  Debug file
                    written.
                    @PARSEONLY  Keystrokes not sent to application.
                    Debug file written.

        Returns:
          (integer) previous SKDebug mode.

        Note: File C:\SKDEBUG.TXT contains parsed keystrokes

        Example:
          Run("notepad.exe", "")
          SKDebug(@ON)
          SendKey("!FO*.*~")
          SKDebug(@OFF)

        See Also:
          SendKey






                                                                       79

        WBL FUNCTION REFERENCE



        StrCat

        Concatenates two or more strings.

        Syntax:
          StrCat (string1, string2[, stringN]...)

        Parameters:
          "string1", etc =  at least two strings you want to "string"
                    together (so to speak).

        Returns:
          (string)  concatenation of the entire list of input strings.

        Use this command to stick character strings together, or to
        format display messages.

        Errors:
          2058 "StrCat function syntax error"

        Example:
          user = AskLine("Login", "Your Name:", "")
          Message("Login", StrCat("Hi, ", user))
          ; note that this will do the same:
          Message("Login", "Hi, %user%")

        See Also:
          StrFill, StrFix, StrTrim



        StrCmp

        Compares two strings.

        Syntax:
          StrCmp (string1, string2)

        Parameters:
          "string1", "string2" =
                    strings to compare.

        Returns:
          (integer) -1, 0, or 1; depending on whether string1 is less
                    than, equal to, or greater than string2,
                    respectively.

        Use this command to determine whether two strings are equal, or
        which precedes the other in an ASCII sorting sequence.
        Note:  This command has been included for semantic completeness.
        The relational operators >, >=, ==, !=, <=, and < provide the
        same capability.







        80

                                                   WBL FUNCTION REFERENCE



        Example:
          a = AskLine("STRCMP", "Enter a test line", "")
          b = AskLine("STRCMP", "Enter another test line", "")
          c = StrCmp(a, b)
          c = c + 1
          d = StrSub("less than   equal to    greater     than", c * 12,
            12)
          ; Note that above string is grouped into 12-character chunks.
          ; Desired chunk is removed with the StrSub statement.
          Message("STRCMP", "%a% is %d% %b%")

        See Also:
          StrICmp, StrIndex, StrLen, StrScan, StrSub



        StrFill

        Creates a string filled with a series of characters.

        Syntax:
          StrFill (filler, length)

        Parameters:
          "filler" =   a string to be repeated to create the return
                    string.  If the filler string is null, spaces will
                    be used instead.
          length =  the length of the desired string.

        Returns:
          (string)  character string.

        Use this function to create a string consisting of multiple
        copies of the filler string concatenated together.

        Example:
          Message("My Stars", StrFill("*", 30))

        See Also:
          StrCat, StrFix, StrLen, StrTrim



        StrFix

        Pads or truncates a string to a fixed length.

        Syntax:
          StrFix (base-string, pad-string, length)

        Parameters:
          "base-string" =   string to be adjusted to a fixed length.
          "pad-string" = appended to "base-string" if needed to fill out
                    the desired length.  If "pad-string" is null, spaces
                    are used instead.




                                                                       81

        WBL FUNCTION REFERENCE



          length =  length of the desired string.

        Returns:
          (string)  fixed size string.

        This function "fixes" the length of a string, either by
        truncating it on the right, or by appending enough copies of pad-
        string to achieve the desired length.

        Example:
          a = StrFix("Henry", " ", 15)
          b = StrFix("Betty", " ", 15)
          c = StrFix("George", " ", 15)
          Message("Spaced Names", StrCat(a, b, c))

        See Also:
          StrFill, StrLen, StrTrim



        StriCmp

        Compares two strings without regard to case.

        Syntax:
          StrICmp (string1, string2)

        Parameters:
          "string1", "string2" = strings to compare.

        Returns:
          (integer) -1, 0, or 1; depending on whether string1 is less
                    than, equal to, or greater than string2,
                    respectively.

        Use this command to determine whether two strings are equal, or
        which precedes the other in an ACSII sorting sequence, when case
        is ignored.

        Example:
          a = AskLine("STRICMP", "Enter a test line", "")
          b = AskLine("STRICMP", "Enter another test line", "")
          c = StriCmp(a, b)
          c = c + 1
          d = StrSub("less than   equal to    greater than", c * 12, 12)
          ; Note that above string is grouped into 12-character chunks.
          ; Desired chunk is removed with the StrSub statement.
          Message("STRICMP", "%a% is %d% %b%")

        See Also:
          StrCmp, StrIndex, StrLen, StrScan, StrSub








        82

                                                   WBL FUNCTION REFERENCE



        StrIndex

        Searches a string for a substring.

        Syntax:
          StrIndex (string, sub-string, start, direction)

        Parameters:
          "string" =   the string to be searched for a substring.
          "substring" =  the string to look for within the main string.
          start =   the position in the main string to begin the search.
                    The first character of a string is position 1.
          direction =  the search direction.  @FWDSCAN searches forward,
                    while @BACKSCAN searches backwards.

        Returns:
          (integer) position of "sub-string" within "string";
                    0 if not found.

        This function searches for a substring within a "target" string.
        Starting at the "start" position, it goes forward or backward
        depending on the value of the "direction" parameter.  It stops
        when it finds the "substring" within the "target" string, and
        returns its position.

        A start position of 0 has special meaning depending on which
        direction you are scanning.  For forward searches zero indicates
        the search should start at the beginning of the string.  For
        reverse searches zero causes it to start at the end of the
        string.

        Errors:
          3100 "StrIndex/StrScan 3rd parameter out of bounds"

        Example:
          instr = AskLine("STRINDEX", "Type a sentence:", "")
          start = 1
          end = StrIndex(InStr, " ", start, @FWDSCAN)
          If end == 0 Then Goto error
          Message("STRINDEX", StrCat("The first word is: ",
            StrSub(instr, start, end - 1))
          Exit
          :error
          Message("Sorry...", "No spaces found")

        See Also:
          StrLen, StrScan, StrSub



        StrLen

        Provides the length of a string.

        Syntax:
          StrLen (string)



                                                                       83

        WBL FUNCTION REFERENCE



        Parameters:
          "string" =   any text string.

        Returns:
          (integer) length of string.

        Use this command to determine the length of a string variable or
        expression.

        Example:
          myfile = AskLine("Filename", "File to process:", "")
          namlen = StrLen(myfile)
          If namlen > 13 Then Message("", "Filename too long!")

        See Also:
          StrFill, StrFix, StrIndex, StrScan, StrTrim



        StrLower

        Converts a string to lowercase.

        Syntax:
          StrLower (string)

        Parameters:
          "string" =   any text string.

        Returns:
          (string)  lowercase string.

        Use this command to convert a text string to lower case.

        Example:
          a = AskLine("STRLOWER", "Enter text", "")
          b = strlower(a)
          message(a, b)

        See Also:
          StrICmp, StrUpper



        StrReplace

        Replaces all occurances of a substring with another.

        Syntax:
          StrReplace (string, old, new)

        Parameters:
          "string" =   string in which to search.
          "old" =   target substring.
          "new" =   replacement substring.





        84

                                                   WBL FUNCTION REFERENCE



        StrReplace scans the 'string', searching for occurrences of 'old'
        and replacing each occurrence with 'new'.  'String' is modified
        directly.

        Example:
          ; Copy highlighted files to clipboard
          a = FileItemize("")
          crlf = StrCat(Num2Char(13), Num2Char(10))
          StrReplace(a, " ", crlf)
          ClipPut(a)



        StrScan

        Searches string for occurrence of delimiters.

        Syntax:
          StrScan (string, delimiters, start, direction)

        Parameters:
          "string" =   the string that is to be searched.
          "delimiters" = a string of delimiters to search for within
                    "string".
          start =   the position in the main string to begin the search.
                    The first character of a string is  position 1.
          direction =  the search direction.  @FWDSCAN searches forward,
                    while @BACKSCAN searches backwards.

        Returns:
          (integer) position of delimiter in string, or 0 if not found.

        This function searches for delimiters within a target "string".
        Starting at the "start" position, it goes forward or backward
        depending on the value of the "direction" parameter.  It stops
        when it finds any one of the characters in the "delimiters"
        string within the target "string".

        Errors:
          3100 "StrIndex/StrScan 3rd parameter out of bounds"

        Example:
          thestr = "123,456.789:abc"
          start = 1
          end = StrScan(thestr, ",.:", start, @FWDSCAN)
          If end == 0 Then Goto error
          Message("The first parameter", StrSub(thestr, start, end -
            start + 1))
          Exit
          :error
          Message("Sorry...", "No delimiters found")

        See Also:
          StrLen, StrSub






                                                                       85

        WBL FUNCTION REFERENCE



        StrSub

        Extracts a substring out of an existing string.

        Syntax:
          StrSub (string, start, length)

        Parameters:
          "string" =   the string from which the substring is to be
                    extracted.
          start =   character position within "string" where the sub-
                    string starts.  (The first character of the string
                    is at position 1).
          length =  length of desired substring.  If you specify a
                    length of zero it will return a null string.

        Returns:
          (string)  substring of parameter string.

        This function extracts a substring from within a "target" string.
        Starting at the "start" position, it copies up to "length"
        characters into the substring.

        Errors:
          3059 "Illegal Bounds for STRSUB function"

        Example:
          a = "My dog has fleas"
          animal = StrSub(a, 4, 3)
          Message("STRSUB", "My animal is a %animal%")

        See Also:
          StrLen, StrScan



        StrTrim

        Removes leading and trailing spaces from a character string.

        Syntax:
          StrTrim (string)

        Parameters:
          "string" =   a string with unwanted spaces at the beginning
                    and/or the end.

        Returns:
          (string)  string devoid of leading and trailing spaces.

        Use this function to remove unwanted spaces from the beginning
        and end of text data.






        86

                                                   WBL FUNCTION REFERENCE



        Example:
          thefile = AskLine("STRTRIM", "Filename ('exit' cancels)", "")
          tstexit = StrTrim(StrLower(thefile))
          If tstexit == "exit" Then Goto cancel
          ; processing of thefile continues...
          : cancel
          Message("Canceled", "...by user request")

        See Also:
          StrFill, StrFix, StrLen



        StrUpper

        Converts a string to uppercase.

        Syntax:
          StrUpper (string)

        Parameters:
          "string" =   any text string.

        Returns:
          (string)  uppercase string.

        Use this function to convert a text string to upper case.

        Example:
          a = AskLine("STRUPPER", "Enter text","")
          b = StrUpper(a)
          message(a, b)

        See Also:
          StrICmp, StrLower



        TextBox

        Displays a file in a listbox on the screen and returns selected
        line, if any.

        Syntax:
          TextBox (title, filename)

        Parameters:
          "title" = listbox title.
          "filename" = file containing contents of listbox.

        Returns:
          (string) =   highlighted string, if any.

        The TextBox command loads a file into a Windows listbox and
        displays the listbox to the user.  The command has two primary
        uses:  First off, it can be used to display multi-line messages




                                                                       87

        WBL FUNCTION REFERENCE



        to the user.  In addition, because of its ability to return a
        selected line, it may be used as a multiple choice question box.
        The line highlighted by the user (if any) will be returned to the
        program.

        If disk drive and path not are part of the filename,  the current
        directory will be examined first, and then the DOS path will be
        searched to find the desired file.

        Example:
          ; Display config.sys
          a = TextBox("Choose a line", "C:\CONFIG.SYS")
          Display(3, "Chosen line", a)

        See Also:
          ItemSelect



        Version

        Returns the version number of the currently-running WinBatch
        language processor.

        Syntax:
          Version ( )

        Returns:
          (string) =   WinBatch version number.

        Use this function to determine the version of WinBatch that is
        running.  It is useful to verify that a batch file generated with
        the latest version of the language will operate properly on what
        may be a different machine with a different version of WinBatch
        installed.

        Example:
          a = Version()

        See Also:
          Environment, WinVersion



        WinActivate

        Activates a previously running window.

        Syntax:
          WinActivate (partial-windowname)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  The most-recently used window whose title
                    matches the name will be activated.




        88

                                                   WBL FUNCTION REFERENCE



        Returns:
          (integer) @TRUE if a window was found to activate;
                    @FALSE if no windows were found.

        Use this command to activate windows for user input.

        Errors:
          1045 "WinActivate: Window not found"

        Example:
          Run("notepad.exe", "")
          Run("clock.exe", "")
          WinActivate("Notepad")

        See Also:
          WinCloseNot, WinGetActive, WinShow



        WinArrange

        Arranges, tiles, and/or stacks application windows.

        Syntax:
          WinArrange (style)

        Parameters:
          style =   one of the following:  @STACK, @TILE (or @ARRANGE),
                    @ROWS, or @COLUMNS.
        Returns:
          (integer) always @TRUE.

        Use this command to rearrange the open windows on the screen.
        (Any iconized programs are unaffected.)

        When you specify @ROWS and you have more than four open windows,
        or if you specify @COLUMNS and you have more than three open
        windows, WinBatch will revert to @TILE.

        Example:
          ; Reveal all windows
          WinArrange(@TILE)

        See Also:
          WinItemize, WinHide, WinIconize, WinPlace, WinShow, WinZoom



        WinClose

        Closes an open window.

        Syntax:
          WinClose (partial-windowname)





                                                                       89

        WBL FUNCTION REFERENCE



        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  The most-recently used window whose title
                    matches the name will be closed.

        Returns:
          (integer) @TRUE if a window was found to close;
                    @FALSE if no windows were found.

        Use this command to close windows.
        This command will not close the current WinBatch window.  You
        can, however, call EndSession to end the current Windows session.

        Errors:
          1039 "WinClose: Window not found"

        Example:
          Run("notepad.exe", "")
          WinClose("Notepad")

        See Also:
          WinCloseNot, WinHide, WinIconize, WinWaitClose



        WinCloseNot

        Closes all windows, except those provided as parameters:.

        Syntax:
          WinCloseNot (partial-windowname [, partial-windowname]...)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  Any windows whose titles match the partial
                    names will stay open.

        Returns:
          (integer) always @TRUE.

        Use this command to close all windows except those specifically
        listed in the parameter strings.

        At least one partial windowname must be given.  A null-string
        parameter would match all windows, or in other words close
        nothing.












        90

                                                   WBL FUNCTION REFERENCE



        Errors:
          2038 "WinCloseNot Function Syntax error"

        Example:
          ; The statement below will close all windows except:
          ; 1) MS-DOS Executive (starts with 'MS-D')
          ; 2) Clock  (starts with 'Clo' )
          WinCloseNot("MS-D", "Clo")

        See Also:
          WinItemize, WinClose, WinHide, WinIconize, WinWaitClose



        WinConfig

        Returns WIN3 mode flags.

        Syntax:
          WinConfig ()


        Returns the Windows configuration information as a number.  Bits
        are defined as follows:

          1     Protected Mode
          2     80286 CPU
          4     80386 CPU
          8     80486 CPU
          16    Standard Mode
          32    Enhanced Mode
          64    8086 CPU
          128   80186 CPU
          256   Large PageFrame
          512   Small PageFrame
          1024  80x87 Installed



        WinExist

        Tells if Window exists.

        Syntax:
          WinExist (partialwindowname)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.

        Returns:
          (integer) @TRUE if a matching window is found.
                    @FALSE if a matching window is not found.

        Note: The partial window name you give must match the initial
        portion of the window name (as appears in the title bar) exactly,
        including proper case (upper or lower) and punctuation.

                                                                       91

        WBL FUNCTION REFERENCE



        Example:
          If WinExist("Clock") == @FALSE Then RunIcon("Clock", "")



        WinGetActive

        Gets the title of the active window.

        Syntax:
          WinGetActive ( )

        Returns:
          (string)  title of active window.

        Use this command to determine which window is currently active.

        Example:
          currentwin = WinGetActive()

        See Also:
          WinItemize, WinActivate



        WinHide

        Hides a window.

        Syntax:
          WinHide (partial-windowname)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  The most-recently used window whose title
                    matches the name will be hidden.

        Returns:
          (integer) @TRUE if a window was found to hide;
                    @FALSE if no windows were found.

        Use this command to hide windows.  The programs are still running
        when they are hidden.

        A partial-windowname of "" hides the current WinBatch window.

        Errors:
          1040 "WinHide: Window not found"

        Example:
          Run("notepad.exe", "")
          WinHide("Notepad")
          WinShow("Notepad")

        See Also:
          WinClose, WinIconize, WinPlace


        92

                                                   WBL FUNCTION REFERENCE



        WinIconize

        Iconizes a window.

        Syntax:
          WinIconize (partial-windowname)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  The most-recently used window whose title
                    matches the name will be iconized.

        Returns:
          (integer) @TRUE if a window was found to iconize;
                    @FALSE if no windows were found.

        Use this command to turn a window into an icon at the bottom of
        the screen.

        A partial-windowname of "" iconizes the current WinBatch window.

        Errors:
          1041 "WinIconize: Window not found"

        Example:
          Run("clock.exe", "")
          WinIconize("Clo")   ; partial window name used here

        See Also:
          WinClose, WinHide, WinPlace, WinShow, WinZoom



        WinItemize

        Returns a tab-delimited list of all open windows.

        Syntax:
          WinItemize ( )

        Returns:
          (string)  list of all open windows' titles.

        This function compiles a list of all the open application
        windows' titles and separates the titles by tabs.  This is
        especially useful in conjunction with the ItemSelect function,
        which enables the user to choose an item from such a tab-
        delimited list.

        Note this behaves somewhat differently than FileItemize and
        DirItemize, which create space-delimited lists.  This is because
        window titles regularly contain embedded spaces.






                                                                       93

        WBL FUNCTION REFERENCE



        Example:
          ; Find a window
          allwins = WinItemize()
          htab = Num2Char(9)
          mywind = ItemSelect("Windows", allwins, htab)
          WinActivate(mywind)

        See Also:
          DirItemize, FileItemize, ItemSelect



        WinPlace

        Places a window anywhere on the screen.

        Syntax:
          WinPlace (x-ulc, y-ulc, x-brc, y-brc, partial-windowname)

        Parameters:
          x-ulc =   how far from the left of the screen to place the
                    upper-left corner (0-1000).
          y-ulc =   how far from the top of the screen to place the
                    upper-left corner (0-1000).
          x-brc =   how far from the left of the screen to place the
                    bottom-right corner (10-1000) or @NORESIZE.
          y-brc =   how far from the top of the screen to place the
                    bottom-right corner (10-1000) or @NORESIZE or
                    @ABOVEICONS.
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  The most-recently used window whose title
                    matches the name will be moved to the new position.

        Returns:
          (integer) @TRUE if a window was found to move;
                    @FALSE if no windows were found.

        Use this command to move windows on the screen.  (You cannot,
        however, move icons or windows that have been maximized to full
        screen.)

        The "x-ulc", "y-ulc", "x-brc", and "y-brc" parameters are based
        on a logical screen that is 1000 points wide by 1000 points high.

        You can move the window without changing the width and/or height
        by specifying @NORESIZE for the "x-brc" and/or "y-brc"
        parameters, respectively.

        You can fix the bottom of the window to sit just above the line
        of icons along the bottom of the screen by specifying a "y-brc"
        of @ABOVEICONS.

        Some sample parameters:

          Upper left quarter of the screen:  0, 0, 500, 500
          Upper right quarter:  500, 0, 500, 1000


        94

                                                   WBL FUNCTION REFERENCE



          Center quarter:  250, 250, 750, 750
          Lower left eighth:  0, 750, 500, 1000

        A handy utility program is included with WinBatch, called
        WinInfo.exe.  This program lets you take an open window that is
        sized and positioned the way you like it, and automatically
        create the proper WinPlace statement for you.  It puts the text
        into the Clipboard, from which you can paste it into your batch
        code:

        You'll need a mouse to use WinInfo.  While WinInfo is the active
        window, place the mouse over the window you wish to create the
        WinPlace statement for, and press the spacebar.  The new
        statement will be placed into the Clipboard.  Then press the Esc
        key to close WinInfo.

        Errors:
          1044 "WinPlace: Window not found"

        Example:
          WinPlace(0, 0, 200, 200, "Clock")

        See Also:
          WinArrange, WinHide, WinIconize, WinShow, WinZoom



        WinPosition

        Returns Window position.

        Syntax:
          WinPosition (partialwindowname)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.

        Returns:
          (string)  window coordinates, delimited by commas.

        Returns the current Window position information for the selected
        Window.  It returns 4 comma-separated numbers (see WinPlace for
        details).

        Example:
          a = WinPosition("Clock")

        A return value for the above function might be "0,0,100,100".

        See Also:
          WinPlace







                                                                       95

        WBL FUNCTION REFERENCE



        WinShow

        Shows a window in its "normal" state.

        Syntax:
          WinShow (partial-windowname)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  The most-recently used window whose title
                    matches the name will be shown.

        Returns:
          (integer) @TRUE if a window was found to show;
                    @FALSE if no windows were found.

        Use this command to restore a window to its "normal" size and
        position.

        A partial-windowname of "" restores the current WinBatch window.

        Errors:
          1043 "WinShow: Window not found"

        Example:
          RunZoom("notepad.exe", "")
          ; other processing...
          WinShow("Notepad")

        See Also:
          WinArrange, WinHide, WinIconize, WinZoom



        WinTitle

        Changes the title of a window.

        Syntax:
          WinTitle (partial-windowname, new-name)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  The most-recently used window whose title
                    matches the name will be shown.
          "new-name" = the new name of the window.

        Returns:
          (integer) @TRUE if a window was found to rename;
                    @FALSE if no windows were found.

        Use this command to change a window's title.

        A partial-windowname of "" refers to the current WinBatch window.




        96

                                                   WBL FUNCTION REFERENCE



        Note:  Some applications may rely upon their window's title
        staying the same!  It should be used with caution and adequate
        testing.

        Example:
          ; Capitalize title of window
          htab = Num2Char(9)
          allwinds = WinItemize()
          MyWin = ItemSelect("Uppercase Windows", allwinds, htab)
          WinTitle(mywin, StrUpper(mywin))
          Drop(htab, allwinds, mywin)

        See Also:
          WinItemize



        WinVersion

        Provides the version number of the current Windows system.

        Syntax:
          WinVersion (level)

        Parameters:
          level =   either @MAJOR or @MINOR.

        Returns:
          (integer) either major or minor part of the Windows version
                    number.

        Use this command to determine which version of Windows is
        currently running.

        @MAJOR returns the integer part of the Windows version number;
        i.e. 1.0, 2.11, 3.0, etc.

        @MINOR returns the decimal part of the Windows version number;
        i.e. 1.0, 2.11, 3.0, etc.

        Example:
          minorver = WinVersion(@MINOR)
          majorver = WinVersion(@MAJOR)
          Message("Windows Version", StrCat(majorver, ".", minorver))

        See Also:
          Version



        WinWaitClose

        Suspends the batch file execution until a specified window has
        been closed.






                                                                       97

        WBL FUNCTION REFERENCE



        Syntax:
          WinWaitClose (partial-windowname)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  WinWaitClose suspends execution until all
                    matching windows have been closed.

        Returns:
          (integer) @TRUE if at least one window was found to wait for;
                    @FALSE if no windows were found.

        Use this command to suspend the batch file's execution until the
        user has finished using a given window and has manually closed
        it.

        Example:
          Run("clock.exe", "")
          Display(4, "Note", "Close Clock to continue")
          WinWaitClose("Clock")
          Message("Continuing...", "Clock closed")

        See Also:
          Delay, Yield



        WinZoom

        Maximizes a window to full-screen.

        Syntax:
          WinZoom (partial-windowname)

        Parameters:
          "partial-windowname" =
                    either an initial portion of, or an entire window
                    name.  The most-recently used window whose title
                    matches the name will be shown.

        Returns:
          (integer) @TRUE if a window was found to zoom;
                    @FALSE if no windows were found.

        Use this command to "zoom" windows to full screen size.
        A partial-windowname of "" zooms the current WinBatch window.

        Errors:
          1042 "WinZoom: Window not found"

        Example:
          Run("notepad.exe", "")
          WinZoom("Notepad")
          WinShow("Notepad")





        98

                                                   WBL FUNCTION REFERENCE



        See Also:
          WinHide, WinIconize, WinPlace, WinShow



        Yield

        Provides time for other windows to do processing.

        Syntax:
          Yield

        Use this command to give other running windows time to process.
        This command will allow each open window to process 20 or more
        messages.

        Example:
          ;run Excel and give it some time to start up...
          sheet = AskLine ("Excel", "File to run:", "")
          run("Excel.exe", sheet)
          yield
          yield
          yield

        See Also:
          Delay






























                                                                       99

        APPENDIX A    Predefined Constants




                                   APPENDIX A

                              Predefined Constants

        WBL provides you with a number of predefined integer constants to
        help make your batch files more mnemonic:

        Logical Conditions               String Handling

        @FALSE                           @FWDSCAN
        @NO                              @BACKSCAN
        @OFF
        @TRUE                            Menu Handling
        @YES
        @ON                              @ENABLE
                                         @DISABLE
        Window Arranging                 @UNCHECK
                                         @CHECK
        @NORESIZE
        @ABOVEICONS                      System Control
        @STACK
        @ARRANGE                         @MAJOR
        @TITLE                           @MINOR
        @ROWS
        @COLUMNS                         Error Handling

                                         @CANCEL
                                         @NOTIFY
                                         @OFF

                                         Keyboard Status

                                         @SHIFT
                                         @CTRL

























        100

                                                     APPENDIX B    Errors




                                   APPENDIX B

                                     Errors

        If the current error mode is @CANCEL (the default), any WBL
        errors encountered while processing a batch file cause the item
        to be canceled with an error message.


        Minor Errors

        Minor errors are ignored if the current error mode has been set
        to @OFF.  If the error mode is @NOTIFY the user has the option of
        continuing with the batch file or canceling it.

        1006 File Copy/Move: No matching files found
        1017 File Delete: No matching files found
        1018 File Delete: Delete Failed
        1024 File Rename: No matching files found
        1025 File Rename: Rename failed
        1028 LogDisk: Requested drive not online
        1029 DirMake: Dir not created
        1030 DirRemove: Dir not removed
        1031 DirChange: Dir not found/changed
        1039 WinClose: Window not found
        1040 WinHide: Window not found
        1041 WinIconize: Window not found
        1042 WinZoom: Window not found
        1043 WinShow: Window not found
        1044 WinPlace: Window not found
        1045 WinActivate: Window not found


        Moderate Errors

        If the error mode is @NOTIFY or @OFF, the user has the option of
        continuing with the batch file or canceling it.

        2002 File Copy/Move: 'From' file illegal
        2003 File Copy/Move: 'To'   file illegal
        2004 File Copy/Move: Cannot copy/move wildcards into fixed root
        2005 File Copy/Move: Cannot copy/move wildcards into fixed
             extension
        2007 File Move: Unable to rename source file
        2015 File Move:  Unable to remove source file
        2016 File Delete: File name illegal
        2019 File Rename: 'From' file illegal
        2020 File Rename: 'To' file illegal
        2021 File Rename: Attempt to rename across drive boundary. - Use
             MOVE instead.
        2022 File Rename: Cannot rename wildcards into a fixed filename
             root
        2023 File Rename: Cannot rename wildcards into a fixed filename
             extension




                                                                      101

        APPENDIX B    Errors



        2038 WinCloseNot Function Syntax error
        2058 StrCat function syntax error
        2060 Average function syntax error


        Fatal Errors

        Fatal errors cause the current batch file to be canceled with an
        error message, regardless of the error mode in effect.  (We show
        the error codes here for consistency, but in practice you will
        never be able to call LastError after a fatal error.)

        3008 File Copy/Move: 'From' file open error
        3011 File Copy/Move: 'From' file length error
        3012 File Copy/Move: No room left on disk.  Out of space??
        3013 File Copy/Move: 'To' file open error
        3014 File Copy/Move: I/O Error
        3026 LogDisk: Illegal disk drive
        3027 LogDisk: DOS reports no disks!!  ???
        3034 Clipboard owned by another app.  Cannot open.
        3035 Clipboard does not contain text for ClipAppend.
        3036 Clipboard cannot hold that much text (>64000 bytes)
        3037 Unable to allocate memory for clipboard.  Close some
             applications
        3046 Internal Error 3046. Function not defined
        3047 Variable name over 30 chars. Too Long
        3048 Substitution %Variable% not followed by a % (Use %% for %)
        3049 No variables exist??!!
        3050 Undefined variable
        3051 Undefined variable or function
        3052 Uninitialized variable or undefined function
        3053 Character string too long (>256 chars??)
        3054 Unrecognizable item found on line
        3055 Variable name is over 30 chars. Too Long
        3056 Variable could not be converted to string
        3057 Variable could not be converted to integer
        3059 Illegal Bounds for StrSub function
        3061 Illegal Syntax
        3062 Attempt to divide by zero
        3063 Internal Error 3063. Binary op not found
        3064 Internal Error 3064. Unary op not found
        3065 Unbalanced Parenthesis
        3066 Wrong Number of Arguments in Function
        3067 Function Syntax. Opening parenthesis missing.
        3068 Function Syntax. Illegal delimiter found.
        3069 Illegal assignment statement. (Use == for equality testing)
        3070 Internal error 3070.  Too many arguments defined.
        3071 Missing or incomplete statement
        3074 Expression continues past expected end.
        3081 FileRead: Invalid file handle
        3082 FileRead: File not currently open
        3084 FileWrite: Invalid file handle
        3085 FileWrite: File not currently open
        3087 FileRead:  File not open for reading





        102

                                                     APPENDIX B    Errors



        3088 FileRead: Attempt to read past end of file
        3089 FileWrite: File not open for writing
        3095 Compare could not be resolved into a integer or string
             compare
        3096 Memory allocation failure.  Out of memory for string storage
        3097 Memory allocation failure.  Out of memory for variable
             storage
        3098 Internal error, NULL pointer passed to xstrxxx subroutines
        3100 StrIndex/StrScan 3rd parameter out of bounds
        3101 Substituted line too long. (> 256 characters)
        3102 Drop: Can only drop variables
        3103 IsDefined: Attempting to test non-variables item
        3107 Run:  Filetype is not COM, EXE, PIF or BAT
        3108 FileItemize: Unable to lock file info segment
        3109 FileItemize: Unable to unlock file info segment
        3110 FileItemize: Unable to lock file index segment
        3111 FileItemize: Unable to unlock file index segment
        3112 FileSize:  File Not Found
        3113 FileSize:  Filelength I/O Error
        3114 FileSize:  Buffer Overrun Error
        3115 FileDelete: Buffer Overrun Error
        3116 FileRename: Buffer Overrun Error
        3117 FileCopyMove: Buffer Overrun Error
        3118 FileCopyMove: Destination file same as source


































                                                                      103

                                                                    Index




                                     Index

                                           minor  101
        A                                  moderate  101-102
        Abs  36,40                         see also   Debug,
        AskLine  12,32,40-41                   ErrorMode, LastError
        AskYesNo  12,32,41               Exclusive  37,55
        Average  36,41-42                Execute  37,54
                                         Exit  37,54-55
        B
        batch files                      F
         error handling  31-32           File Management
         statement summary  32-37          in WBL  32-33
         statements  37-100              FileClose  32,55-56
         WBL language components  27-    FileCopy  17,32,55-56
         31                              FileDelete  17,32,56-57
        Beep  12,32,13                   FileExist  17,32,57-58
                                         FileExtension  33,58
        C                                FileItemize  20,33,58-59
        Call  36,42                      FileLocate  33,59-60
        CallExt  36,42-43                FileMove  33,60
        Char2Num  35,42-43               FileOpen  33,60-61
        ClipAppend  36,43-44             FilePath  33,61
        ClipGet  36,44-45                FileRead  33,61-62
        ClipPut  36,45                   FileRename  17,33,60-63
        Comments  30                     FileRoot  33,63
        Constants  27-28                 FileSize  33,63-64
         predefined  27-28               FileWrite  33,64

        D                                G
        DateTime  36,45-46               Goto  37,64
        Debug  36,46-47
        Delay  13,36,47                  I
                     Identifiers  28
        DirChange  16,33,47-48           If_Then  37,64-65
        Directory Management             IgnoreInput  37,65
         in WBL  33                      IniRead  37,64-66
        DirGet  16,33,48                 IniReadPvt  37,66
        DirHome  33,48-49                IniWrite  37,66-67
        DirItemize  21,33,49             IniWritePvt  37,67
        DirMake  33,49-50                IsDefined  37,67-68
        DirRemove  33,50                 IsKeyDown  37,68
        DiskFree  33,50-51               IsLicensed  37,68-69
        Display  12,32,51                IsNumber  35,68-69
        DOSVersion  36,51-52             ItemSelect  20,32,69-70
        Drop  36,51-52
                                         K
        E                                Keywords  28
        EndSession  16,36,52-53
        Environment  24,36,53            L
        ErrorMode  18,36,19              LastError  37,70-71
        Errors  31-32,101-107            LogDisk  33,71
         fatal  102-107




                                                                      105





                                         StrIndex  35,83
        M                                StrLen  35,83-84
        Max  36,71-72                    StrLower  35,84
        Message  12,32,72                StrReplace  35,84-85
        Microsoft Windows                StrScan  35,84-86
         date & time formatting  45      StrSub  35,86
         determining the version         StrTrim  35,86-87
         37,97                           StrUpper  35,87
         ending the session  52          Substitution  30-31
        Min  36,72-73                      and StrCat  78-80

        N                                T
        Num2Char  22,35,72-73            TextBox  32,87-88

        O                                V
        Operators  28-29                 Variables  28
         Precedence  29                  Version  37,88

        P                                W
        ParseData  35,73-74              WinActivate  14,34,88-89
        Pause  12,32,73-74               WinArrange  34,89
                                         WinClose  14,34,89-90
        R                                WinCloseNot  14,34,90-91
        Random  36,74                    WinConfig  34,91
        Registration  109                Window Management
        Return  37,74-75                   in WBL  33-34
        Run  11,34,74-75                 WinExist  15,34,91-92
        RunHide  34,75-76                WinGetActive  34,91-92
        RunIcon  11,34,76-77             WinHide  34,92-93
        Running programs                 WinIconize  13,34,93
         in WBL  34-35                   WinItemize  34,93-94
        RunZoom  11,35,77-78             WinPlace  34,94-95
                                         WinPosition  34,95
        S                                WinShow  13,34,95-96
        SendKey  24,37,78-79             WinTitle  34,96-97
        SKDebug  37,79                   WinVersion  37,97
        Statements  30                   WinWaitClose  15,34,97-98
         reference  37-100               WinZoom  13,34,98-99
        StrCat  23,35,78-80
        StrCmp  35,80-81                 Y
        StrFill  35,81                   Yield  37,99
        StrFix  35,81-82
        StrICmp  35,82-83















        106





                                   I want my OWN copy
                                      of WinBatch!
                                   Please send it to:



          Company:__________________________________________________________

             Name:__________________________________________________________

          Address:__________________________________________________________

             City:_____________________________St:__________Zip:____________


            Phone:(_____)___________________  Country: _____________________



                         ____WinBatch(es) @$69.95 ea.:____________

          Foreign air shipping (except Canada) @$9.50:____________

                                                Total:____________

          Please enclose a check payable to Wilson WindowWare; or you may use
          Visa, Master Card, or EuroCard.  For charge cards, please enter
          the information below:

          Card number:   __ __ __ __-__ __ __ __-__ __ __ __-__ __ __ __
          Expiration date: _______/______

          Signature:_________________________________________________________


               Send to:  Wilson WindowWare
                          2701 California Ave SW #212
                          Seattle, WA 98116
                          USA

               or call:     [phone]
                            [phone]  (fax)

                        (Please allow 2 to 4 weeks for delivery)